Variables

Codefresh provides a set of predefined variables automatically in each build, that you can use to parameterize the way your pipeline works. You can also define your own variables. Some common examples of predefined variables include:

  • CF_BRANCH is the git branch that was used for this pipeline.
  • CF_REVISION is the git hash that was used for this pipeline.
  • CF_BUILD_URL is the url of the pipeline build.

Using Codefresh variables in your pipelines

There are two ways to use a Codefresh variable in your pipelines:

  1. By default all variables will be exposed as UNIX environment variables in all freestyle steps as $MY_VARIABLE_EXAMPLE.
  2. Variables can be used in YAML properties with the syntax ${{MY_VARIABLE_EXAMPLE}}.

If you are unsure about which form you need to use, feel free to use ${{MY_VARIABLE_EXAMPLE}} everywhere. This is the Codefresh specific form and should function in all sections of codefresh.yml.

For example, you can print out the branch as an environment variable like this:

YAML

MyOwnStep:
  title: Variable example
  image: alpine
  commands: 
    - echo $CF_BUILD_ID 
    - echo $CF_BRANCH_TAG_NORMALIZED 

In the example above we are using simple echo commands, but any program or script that reads environment variables could also read them in the same manner.

Using variables directly in yaml properties can be done like this:

YAML

MyAppDockerImage:
  title: Building Docker Image
  type: build
  image_name: my-own-app
  tag: ${{CF_BRANCH_TAG_NORMALIZED}}

You can also concatenate variables:

YAML

MyAppDockerImage:
  title: Building Docker Image
  type: build
  image_name: my-own-app
  tag: ${{CF_BRANCH_TAG_NORMALIZED}}-${{CF_SHORT_REVISION}}

This will create docker images with tags such as:

master-df6a04c
develop-ba1cd68
feature-vb145dh

Notice that this syntax is specific to Codefresh and is only available within the Codefresh YAML file itself. If you want to write scripts or programs that use the Codefresh variables, you need to make them aware of the environment variable form.

System Provided Variables

All system provided variables will also be automatically injected to any freestyle step as environment variables.

Variable Description
${{CF_REPO_OWNER}} Repository owner.
${{CF_REPO_NAME}} Repository name.
${{CF_BRANCH}} Branch name (or Tag depending on the payload json) of the Git repository of the main pipeline, at the time of execution.
You can also use ${{CF_BRANCH_TAG_NORMALIZED}} to get the branch name normalized. It will be without any chars that are illegal in case the branch name were to be used as the Docker image tag name.
${{CF_BASE_BRANCH}} The base branch used during creation of Tag
${{CF_PULL_REQUEST_ACTION}} The pull request action. Values are those defined by your Git provider such as Github, Gitlab, Bitbucket etc.
${{CF_PULL_REQUEST_TARGET}} The pull request target branch
${{CF_PULL_REQUEST_NUMBER}} The pull request number
${{CF_PULL_REQUEST_ID}} The pull request id
${{CF_PULL_REQUEST_LABELS}} The labels of pull request (Github and Gitlab only)
${{CF_COMMIT_AUTHOR}} Commit author.
${{CF_BUILD_INITIATOR}} The person (username) that started the build. If the build was started by a Git webhook (e.g. from a Pull request) it will hold the webhook user. Notice that if a build is restarted manually it will always hold the username of the person that restarted it.
${{CF_ACCOUNT}} Codefresh account for this build
${{CF_COMMIT_URL}} Commit url.
${{CF_COMMIT_MESSAGE}} Commit message of the git repository revision, at the time of execution.
The messages quotes are escaped (i.e. ‘ is not ', “ is now ").
${{CF_REVISION}} Revision of the Git repository of the main pipeline, at the time of execution.
You can also use ${{CF_SHORT_REVISION}} to get the abbreviated 7-character revision hash, as used in git. Note: use this variable as string with quotes to tag the image ${{CF_SHORT_REVISION}}
${{CF_VOLUME_NAME}} Refers to the shared volume between freestyle steps. Normally you only need to define this in compositions. In freestyle steps, it is automatically present without any extra configuration.
${{CF_VOLUME_PATH}} Refers to the mounted path of the shared volume inside a Freestyle container. In the current implementation it expands to /codefresh/volume.
${{CF_BUILD_TRIGGER}} Will be an indication of the current build was triggered: build: The build was triggered from the build button webhook: The build was triggered from a control version webhook
${{CF_BUILD_ID}} The build id. Note: use this variable as string with quotes to tag the image ${{CF_BUILD_ID}}
${{CF_BUILD_TIMESTAMP}} The timestamp the build was created. Note: use this variable as string with quotes to tag the image ${{CF_BUILD_TIMESTAMP}}
${{CF_BUILD_URL}} The URL to the build in Codefresh
${{CF_URL}} The URL of Codefresh system
${{CI}} The value is always true
${{CF_KUBECONFIG_PATH}} Path to injected kubeconfig if at least one Kubernetes cluster is configured. You can easily run custom kubectl commands since it is automatically setup by Codefresh in all pipelines.
Any variable specified in the pipeline settings For example, if you configure the pipeline settings with a variable named PORT, you can put the variable in your YAML build descriptor as ${{PORT}}.

Context related variables are created dynamically during the workflow execution and according to the used steps.

Variable Description
Working Directories For example, you can set the working directory of step A with a variable named after a previously executed step, step B. Therefore, setting step A with working-directory:${{B}} means that step A executes in the same working directory as step B.
Images You can set the candidate field of the push step with a variable named after a previously executed build step. Since the details of a created image are not necessarily known ahead of time, the variable can create an association to an optionally dynamic image name. Therefore, setting push step A with candidate:${{B}} means that step A will push the image built by step B.

A very common pattern in Codefresh pipelines, is to create a Docker image in one step, and then run a command on its container in the next step (e.g. run unit tests):

YAML

version: '1.0'
steps:
  MyAppDockerImage:
    title: Building Docker Image
    type: build
    image_name: my-own-app
  MyUnitTests:
    title: Running Unit tests
    image: ${{MyAppDockerImage}}
    commands: 
      - ./my-unit-tests.sh

In the example above you can see the MyAppDockerImage variable that denotes a Docker image created dynamically within this single pipeline. In the second step we use it as a Docker context in order to run unit tests. See also the unit testing example app.

GitHub Release Variables

GitHub allows you to create releases for marking specific git tags for general availability.

You can set a trigger for GitHub releases. When a GitHub release happens, the following variables are also available:

Variable Description
${{CF_RELEASE_NAME}} Github release title
${{CF_RELEASE_TAG}} GIT tag version
${{CF_RELEASE_ID}} Internal ID for this release
${{CF_PRERELEASE_FLAG}} true if the release if marked as non-production ready, false if it is ready for production

GitHub Pull Request Variables

When a pull request is closed in GitHub, the following variables are also available

Variable Description
${{CF_PULL_REQUEST_MERGED}} true if the pull request was merged to base branch
${{CF_PULL_REQUEST_HEAD_BRANCH}} the head branch of the PR (the branch that we want to merge to master)
${{CF_PULL_REQUEST_MERGED_COMMIT_SHA}} the commit SHA on the base branch after the pull request was merged (in most cases it will be master)
${{CF_PRERELEASE_FLAG}} the commit SHA on the head branch (the branch that we want to push)

User Provided Variables

User provided variables can be defined at 4 levels:

  1. Freestyle Step Definition (using the environment field)
  2. Pipeline Execution (after clicking the “Build” button, open the “Advanced options” section)
  3. Pipeline Definition (under “Environment variables” section in the pipeline view)
  4. Shared Configuration (defined under your account settings, and used using the “Import from shared configuration” button under the “Environment Variables” section in the pipeline view)

The options are listed in order of importance, so in case of multiple variables defined at different location with the same name, the order of overriding will be as listed here.

Exporting environment variables from a freestyle step

Steps defined inside steps are scoped to the step they were created in (even if you used the export command). In order to allow using variables across steps, we provide a shared file that facilitates variables importing and exporting. There are two ways to add variables to this file:

Using cf_export command

Inside every freestyle step there’s a command called cf_export that allows you to export variables across steps (by writing to the shared variables file).

You can either:

  • Explicitly state a VAR=VAL pair
  • State the name of an existing exported environment variable (like EXISTING_VAR).
version: '1.0'
steps:
  freestyle-step-1:
    description: Freestyle step..
    title: Free styling
    image: alpine:latest
    commands:
      # Normal export will only work in a single step
      - export EXISTING_VAR=www.example.com

      # CF export will now work in all other subsequent steps
      - cf_export VAR1=alpine:latest VAR2=VALUE2 EXISTING_VAR

  freestyle-step-2:
    description: Freestyle step..
    title: Free styling 2
    image: ${{VAR1}}
    commands:
      - echo $VAR2
      - echo http://$EXISTING_VAR/index.php

Notice that cf_export has the same semantics as the bash export command. This means that when you use it you don’t need any dollar signs for the variable created/assigned.

cf_export $MY_VAR # Don't do this
cf_export MY_VAR # Correct syntax

There is nothing really magic about cf_export. It is a normal script. You can see its contents on your own by entering the command cat /codefresh/volume/cf_export on any Codefresh freestyle step inside a pipeline.

Directly writing to the file

For more advanced use cases, you can write directly to the shared variable file that Codefresh reads to understand which variables need to be available to all steps. This file has a simple format where each line is a variable and its value in the form of VARIABLE=VALUE. The cf_export command mentioned in the previous section is just a shorthand for writing on this file.

The variables file is available inside freestyle steps in the following path: ${{CF_VOLUME_PATH}}/env_vars_to_export

version: '1.0'
steps:
  freestyle-step-1:
    description: Freestyle step..
    title: Free styling
    image: alpine:latest
    commands:
      - echo VAR1=192.168.0.1 >> ${{CF_VOLUME_PATH}}/env_vars_to_export
      - echo hey=alpine:3.9 >> ${{CF_VOLUME_PATH}}/env_vars_to_export
          
  freestyle-step-2:
    description: Freestyle step..
    title: Free styling 2
    image: ${{hey}}
    commands:
      - echo http://$VAR1/index.php
      

Use this technique if you have complex expressions that have issues with the cf_export command.

Escape Characters

When passing special characters through environmental variables \ can be used as an escape character. For example if you were passing a cassandra connection string you might do something like Points\=hostname\;Port\=16376\;Username\=user\;Password\=password

This will safely escape ; and =.