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_BRANCHis the git branch that was used for this pipeline
CF_REVISIONis the git hash that was used for this pipeline
CF_BUILD_URLis the url of the pipeline build
Using Codefresh variables in your pipelines
There are two ways to use a Codefresh variable in your pipelines.
- By default all variables will be exposed as UNIX environment variables in all freestyle steps
- Variables can be used within the
codefresh.ymlitself with the syntax
For example you can print out the branch as an environment variable like this:
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:
You can also concatenate variables:
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.
||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
||The base branch used during creation of Tag|
||The pull request action|
||The pull request target branch|
||The pull request number|
||The pull request id|
||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.|
||Commit message of the git repository revision, at the time of execution.
The messages quotes are escaped (i.e. ‘ is not ', “ is now ").
||Revision of the Git repository of the main pipeline, at the time of execution.
You can also use
||Will refer to the volume that was generated for the specific flow. Can be used in conjunction with a composition to provide access to your cloned repository.For example:test-server: volumes:
||Will refer to the mounted path of the workflow volume inside a Freestyle container.|
||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|
||The build id. Note: use this variable as string with quotes to tag the image
||The timestamp the build was created. Note: use this variable as string with quotes to tag the image
||The URL to the build in Codefresh|
||Path to kubeconfig if at least one Kubernetes cluster is configured|
|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
Context Related Variables
Context related variables are created dynamically during the workflow execution and according to the used steps.
|Working Directories||For example, you can set the working directory of step
|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 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):
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.
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:
||Github release title|
||GIT tag version|
||Internal ID for this release|
||true if the release if marked as non-production ready, false if it is ready for production|
User Provided Variables
User provided variables can be defined at 4 levels:
- Freestyle step definition: using the
- Pipeline execution: after clicking the “Build” button, open the “Advanced options” section.
- Pipeline definition: under “Environment variables” section in the pipeline view.
- 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 environment variable (like EXISTING_VAR).
Directly writing to the file
For more advanced use cases, you can write directly to the shared file.
The variables file will be available inside the freestyle container in the following path:
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
This will safely escape