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 $pipeline_name. This is used when accumulating build info. |
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 $run_number. This is used when accumulating build info. |
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 $project_key. This is used when accumulating or publishing build info. |
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. |
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. pipelines-docker.jfrog.io/jfrog/pipelines-u20node ). |
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 jfrog . |
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
Single Quotes
Example | Result | Comments |
---|---|---|
|
|
|
'This string "uses double quotes"' | This string "uses double quotes" | |
'& this string starts with a special character, needs quotes' | '& this starts with a special character, needs quotes' |
Double Quotes
Example | Result | Comments |
---|---|---|
|
| Double quotes support any character string and escape sequences. For example: |
|
|
Multi-line Strings
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.
|
| hello world |
Literal Style (|)
Example | Result | Comments |
---|---|---|
|
| Literal style preserves end of line characters. This is useful when defining script actions.
|
|
|
Escape Sequences
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 slash- Bash style
"\ "
is used to escape additional spaces that are part of the content and should not be folded - The 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.
Property | Description | Required/Optional |
---|---|---|
default | Default value for the environment variable. | Required |
description | Describes the environment variable usage. This description is displayed in the custom run configuration panel. | Optional |
values | List of values that can be assigned to environment variables when custom run configuration is used in the UI. | Optional |
allowCustom | Determines if users are allowed to use a custom value that is not part of the list of values . Default value is false . | Optional |
pipelines: - name: my_pipeline configuration: environmentVariables: readOnly: env1: value1 env2: default: value1 description: env2 description values: - value1 - value2 - value3 steps: - name: my_step type: Bash configuration: environmentVariables: step_env1: default: value1 description: step env1 description values: - value1 - value2 - value3 allowCustom: true step_env2: value2 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 for step_env2, in addition to the values that are already defined. Note that the custom value is available for a specific run only.
Integrations
A step that uses an integration can access an integration's properties through environment variables. The form of the environment variable is:
int_<integration name>_<tag>
For example, you can access the URL property of an Artifactory Integration named myArtifactory
through an environment variable:
$ printenv int_myArtifactory_url https://mycompany.com/artifactory/
You can also access the properties of an integration through a resource that uses it. The form of the environment variable is:
res_<resource_name>_<integration tag name>_<tag>
For example, an Image resource specifies an Artifactory integration in its registry
tag. You can access the URL of the Artifactory integration used by an Image resource called myImage
as follows:
$ printenv res_myImage_registry_url https://mycompany.com/artifactory/
For more information, see Pipelines Integrations.
Resources
A step that specifies a resource in inputresources
can access the properties of that resource through environment variables. The form of the environment variable is:
res_<resource name>_<tag>
For example, you can access the imageName
property of an Image resource myImage
through an environment variable:
$ printenv res_myImage_imageName jfrog.local:5000/alpine37
Some resources maintain additional properties that may be accessed as environment variables. These resource types include:
For further information see Pipelines Resources.
Resource-based State
Additionally, you can add your own properties to a resource that is specified in outputresources
using the write_output
utility function. This can be used to create stateful pipelines.
The newly attached properties can be accessed as environment variables of the form res_{Resource Name}_{Key Name}
. For example, the following creates three properties in the resource myImage
.
write_output myImage sport="baseball" equipment="bat" field="diamond"
When the resource is specified in a step's inputsources
, these properties can be accessed as the following environment variables:
$ printenv res_myImage_baseball baseball $ printenv res_myImage_equipment bat $ printenv res_myImage_field diamond
For more information on run state, see Creating Stateful Pipelines.
Run State
Your pipeline can define its own environment variables and add them to the pipeline's run state. These will be available to all steps in the run of the pipeline.
Use the utility functions for run state management to add new environment variables to the current run state. For example, the following line in the execution block of a step:
add_run_variables hero="Superman" villain="Lex Luthor"
will create two environment variables available to the current and all future steps of the pipeline's run:
$ printenv hero Superman $ printenv villain Lex Luthor
For more information on run state, see Creating Stateful Pipelines.
Pipeline State
Your pipeline can define its own environment variables and add them to the pipeline state. These will be available to all runs of that pipeline.
Use the utility functions for pipeline state management to add new environment variables to the current run state. For example, the following line in the execution block of a step:
add_pipeline_variables animal="dog" vegetable="carrot"
will create two environment variables available to all run of the pipeline where they were defined:
$ printenv animal dog $ printenv vegetable carrot
For more information on pipeline state, see Creating Stateful Pipelines.