This page describes the availability and usage of environment variables in pipelines.
You can customize your workflow by using environment variables (also called runtime variables) that are available at runtime during step execution. For example, your step can construct a filename or build ID from the pipeline name and current run number. Or your step can execute different commands depending on the state of a resource.
JFrog Pipelines provides access to useful internal information from pipelines and resources through environment variables. Pipelines also provides several easy ways to inject your own environment variables into your runtime during the execution of your pipeline.
Standard Environment Variables
These environment variables are available to all executing pipelines.
Environment Variable | Description |
---|---|
architecture | Node architecture, e.g. x86_64 |
builder_api_token | Token used to call pipelines API during step execution. Used internally but is accessible to user. |
current_script_section | onStart/onExecute/onComplete etc |
JFROG_CLI_BUILD_NAME | If not set as a variable in the YML or added as a pipeline, run, or step variable, it will be set to |
JFROG_CLI_BUILD_NUMBER | If not set as a variable in the YML or added as a pipeline, run, or step variable, it will be set to |
JFROG_CLI_BUILD_PROJECT | If not set as a variable in the YML or added as a pipeline, run, or step variable, it will be set to |
JFROG_PIPELINES_RUN_STATE_DEBUG | To download run state from the UI for debugging purposes, set the environment variable |
operating_system | OS where step is running, e.g. Ubuntu_20.04 |
PATH | The value of PATH in the currently executing runtime environment. |
pipeline_name | The name string of the pipeline currently executing. |
pipelines_api_url | API URL |
project_id | ID of the project in JFrog Pipelines |
project_key | Project key. If the project is the default project, this will be empty. |
project_name | Name of the project |
run_id | Internal unique ID for the run. |
run_number | The number of the run currently executing. |
running_in_container | True if step is running in a container. False if running on host. |
shared_workspace | The path of a directory available to all steps in an affinity group that may be used to share files between steps. |
step_<inputStepName>_statusName | This environment variable is automatically made available at runtime and can be used in any step. inputStepName is the name of your input step. This environment variable is useful for fetching the status of any input step. For an example, see using |
step_affinity_group | Affinity group step belongs to. Default is same as step name. |
step_id | Internal unique ID for the step currently executing. |
step_image_name | Name of the Docker image used to run the step (e.g. |
step_image_tag | Tag of Docker image used to run the step. |
step_name | The name of the step as specified in YAML. |
step_node_id | Internal unique ID for node |
step_node_name | Name of the node used to run step (user-configured when adding node) |
step_node_pool_name | Name of the node pool used to run the step (user configured when creating pool) |
step_platform | Same as operating system. |
step_runtime | Set to "image" or "host" |
step_triggered_by_identity_name | If triggered by a user, name of user. Else empty |
step_triggered_by_resource_name | If triggered by a resource, the name of the resource. Otherwise, this environment variable is empty. |
step_triggered_by_step_name | If triggered by another step, name of step. Else empty |
step_type | The type of step as specified in the field in YAML (e.g., "Bash," "DockerBuild," etc.) |
step_url | Direct link to step |
Reserved Environment Variables
These environment variables have predefined values and cannot be overridden.
Environment Variable | Description |
---|---|
custom_certs_dir | Location of the custom certificates. |
custom_certs_enabled | Indication to use the custom certificates. |
no_verify_ssl | Indication for the step to not verify SSL. |
run_created_at | Time when the run was created. |
step_build_plane_version | The build plane version. |
step_dependency_state_dir | Location where input/output dependency information is stored. |
step_docker_container_name | Name of the container where the step is running. |
step_json_path | Path to the JSON object containing information about the step. |
step_namespace | Pipelines extensions namespace. Default is |
step_timeout_seconds | The total number of seconds that the step can run before it times out. |
step_tmp_dir | Temporary directory used when the step is executing. |
steplet_id | Internal unique ID for the steplet currently executing. |
steplet_number | Unique steplet number in the context of the run. Useful for Matrix steps with multiple steplets. Example onExecute: - add_run_variables steplet_${steplet_number}_variable=${env1} |
User-defined Environment Variables
User-defined environment variables are custom variables that can be defined in the configuration
section of your pipelines YAML file.
Pipelines
In a pipeline, environment variables can be declared within the configuration
section. The environment variables declared here are available to all steps in the pipeline.
pipelines: - name: my_pipeline configuration: environmentVariables: readOnly: env1: value1 env2: value2
Steps
In a step, environment variables can be declared within the configuration
section of the step within a pipeline. The environment variables from this source are available only to the step where they are declared.
steps: - name: step_1 type: Bash configuration: environmentVariables: env1: value1 env2: value2
YAML Schema Reference
When declaring environment variables, it is important to follow YAML syntax conventions and properly quote and escape values to ensure that Pipelines can parse them correctly.
In general, YAML strings are Unicode and can be left unquoted. However, certain rules apply when using special characters. Quotes are required for strings that:
Start with a special character, such as:
:, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, )
Start or end with whitespace characters
Look like a number or boolean (
123
,1.23
,true
,false
,null
)
Examples
Example | Result | Comments |
---|---|---|
'This string 'uses single quotes'' |
|
|
|
| |
'& this string starts with a special character, needs quotes' | '& this starts with a special character, needs quotes' |
Example | Result | Comments |
---|---|---|
|
| Double quotes support any character string and escape sequences. For example: |
"This string uses \ttab" |
|
Multi-line strings can be written using:
Folded Style: Represented by a greater than symbol (>), where each line break is converted to a space.
Literal Style: Represented by a pipe (|), to preserve line breaks.
Folded Style (>)
Example | Result | Comments |
---|---|---|
|
| Folded style removes end of line characters and replaces double end of lines with single lines. This is useful for descriptions.
|
|
|
Literal Style (|)
Example | Result | Comments |
---|---|---|
|
| Literal style preserves end of line characters. This is useful when defining script actions.
|
|
|
YAML uses escape sequences as follows:
\n
is used to represent a new line\t
is used to represent a tab\\
is used to represent a slashBash style
"\ "
is used to escape additional spaces that are part of the content and should not be foldedThe trailing \ is used to represent a continuation marker. This is useful for breaking a long string into multiple lines without introducing unwanted whitespace
Example | Result | Comments |
---|---|---|
|
| Special characters must be escaped with backslash. |
|
| Backticks must be escaped as they are treated specially by the shell. |
|
| |
|
| In this example:
|
Environment Variables Configuration
Besides the key-value syntax, the following properties can also be used under an environment variable definition to enhance its configuration. The following properties are available for environment variables declared in both pipelines and steps configuration
sections.
Important
Environment variable names set at pipeline-level must be unique. A step cannot include the same environment variable name as the one set at the pipeline-level.
Property | Description | Required/Optional | ||
---|---|---|---|---|
| Default value for the environment variable. | Required | ||
| Describes the environment variable usage. This description is displayed in the custom run configuration panel. | Optional | ||
| List of values that can be assigned to environment variables when custom run configuration is used in the UI. | Optional | ||
| Determines if users are allowed to use a custom value that is not part of the list of | Optional | ||
| Secure environment variables are encrypted variables that can be used in your pipelines without exposing their value. These environment variables are ideal for private information, such as passwords. When set as As shown in the example below, the
| Optional |
Example
pipelines: - name: my_pipeline configuration: environmentVariables: readOnly: env1: pipe_value1 env2: default: pipe_value2 description: This is env2 description values: - pipe_value2 - pipe_value3 - pipe_value4 steps: - name: my_step type: Bash configuration: environmentVariables: step_env1: default: step_value1 description: This is step_env1 description values: - step_value1 - step_value2 - step_value3 allowCustom: true step_env2: step_value5 step_env3: allowCustom: true secure: true default: "someValue" execution: onExecute: - echo "test"
When you trigger a run with custom configuration, the UI uses the configurations in the YAML file to control user input in the Run With Custom Configuration panel:
In the YAML, if allowCustom
is set as true
, you can enter any value for that field to define your own value for the run. In the example above, you can enter a custom value forstep_env2, in addition to the values that are already defined. Note that the custom value is available for a specific run only.