Use variables in chains
Use variables in chains to tailor how chains behave on each agent or to provide a way of reusing the same value in multiple steps and chains.
Variable types
You can use chain, agent, and global variables in chain steps. PulseUno also provides a set of native built-in variables to include in chains.
The following table describes the variable types in PulseUno.
Type | Description |
---|---|
Built-in variables |
Native PulseUno variables provide information related to the chain run, for example, the chain number, the changeset ID/commit hash, or the temporary system credentials to authenticate to a vault. For details, see Built-in variables. The values for built-in variables are derived automatically from the system. Built-in variables overwrite any other variables that have the same names. |
Chain variables |
You define chain variables on a chain. When two or more chain steps need the same value, add a chain variable with the necessary value, and reference the variable in multiple chain steps. If a global or agent variable with the same name exists, PulseUno uses the value of the chain variable. For details, see Define chain and global variables. |
Agent variables |
You add agent variables to an agent. They provide information about the agent, for example, the location of a specific compiler. This way, you can reference the compiler location using the variable instead of a fixed value. When the chain runs on the agent, the variable is replaced with the value defined for the agent. If the same variable is defined on the associated chain, PulseUno uses the value of the chain variable. For details, see Add variables to agents. |
Global variables |
Administrators can define global variables. You can use these variables across multiple chains and chain steps. If the same variable is defined on the associated agent or chain, PulseUno uses the value of the agent or chain variable. Chain variables override agent or global variables that have the same names. For details, see Define chain and global variables. |
Built-in variables
You can use the following native PulseUno variables in chain steps.
Variable | Description |
---|---|
fetch_changeset |
The alphanumeric identifier of the changeset checked out in the Fetch Sources step. Has the same value as pulse.changeset_id. |
fetch_stream_name |
The name of the stream or branch checked out in the Fetch Sources step. Dimensions CM streams:PulseUno displays the value in the following format: PRODUCT:STREAM_NAME |
pulse.actor | The name of the user who triggered the chain. If triggered by the system, the value is $system. |
pulse.actor_id | The account ID of the user who triggered the chain. If triggered by the system, the ID is 0. |
pulse.agent_id | The alphanumeric ID of the agent on which the chain runs. |
pulse.agent_name | The name of the agent running the chain. |
pulse.agent.workspace.dir | The location of the agent workspace directory used for the chain run. This is the directory to which the source files are fetched. |
pulse.chain_full_name |
The title of the chain, including the space and product in which the chain runs, for example: my-space/my-product/my-CI-chain |
pulse.chain_name | The title of the chain, for example, my-CI-chain. |
pulse.chain_num chainnum |
The chain run build number. |
pulse.chain_run_id |
The unique ID of the chain run, for example, 5678901. Not the same as pulse.chain_num. |
pulse.chain_run_url |
The URL of the chain run, for example: http://pulseuno:8080/pulse/redirect/chainrun/1234567 |
pulse.changeset_branch | The ID of the source stream/branch for the pull request. If there is no pull request, the name of the stream/branch associated with the changeset. |
pulse.changeset_branch_name stream_name |
The name of the stream or branch associated with the changeset. |
pulse.changeset_branch_version stream_version |
Dimensions CM streams: The stream version that was delivered. PulseUno displays the value in the following format: PRODUCT:STREAM_NAME;VERSION Git branches: Has the same value as pulse.changeset_id. |
pulse.changeset_id changeset_id |
The alphanumeric changeset identifier (stream version) or commit hash. |
pulse.changeset_ref |
Git only: The head reference for the Git branch associated with the changeset, for example: /refs/heads/<my-git-branch> |
pulse.changeset_ref_protected | Git only: Indicates whether the Git branch associated with the changeset is protected by a branch policy (true or false). |
pulse.git_server_url |
The URL of your PulseUno Git server, for example: http://pulseuno:8080/git-server/repo |
pulse.is_pull_request | Indicates whether the chain is running on a pull request (true or false). |
pulse.product product_name |
The name of the product or Git repository in which the chain runs, for example: my-product |
pulse.product_id pulse.repository_id |
The unique ID of the product or Git repository in which the chain runs. These variables have the same value. |
pulse.product_url | The URL of the product or Git repository in which the chain runs. |
pulse.repository |
The space and product/Git repository in which the chain runs, for example: my-space/my-product |
pulse.review_label | The review label or a list of review labels associated with the changeset, for example: Q1234 |
pulse.space suite_name |
The name of the space in which the chain runs. |
pulse.space_id | The unique ID of the space in which the chain runs. |
pulse.target_branch
|
The name of the target stream/branch into which the pull request is merged. |
pulse.target_ref
|
Git only: The head reference for the target Git branch to which the pull request is merged. |
pulse.target_ref_protected | Git only: Indicates whether the target Git branch for the pull request is protected by a branch policy (true/false). |
pulse.url |
The URL of your PulseUno server, for example: http://pulseuno:8080/pulse |
PULSE_VAULT_USERNAME PULSE_VAULT_PASSWORD |
Temporary system credentials that represent a one-time username and password to authenticate to a vault when deploying artifacts. Temporary system credentials are valid only for the duration of the chain run. PulseUno generates the username and password values automatically when a chain is triggered, and invalidates them when the chain finishes. Note: A chain that uses temporary system credentials must run from a trusted product or Git repository. For details, see Define trusted products for vault. |
Note: Built-in variables in the pulse. scope can be converted to environment variables by replacing the pulse. scope with PULSE_. For details about using environment variables in scripts, see Environment variables.
Reference variables in chains
To reference variables in chain steps, use the following syntax: {{variable_name}}
Caution: PulseUno also recognizes the legacy syntax, ${variable_name}. We recommend that you avoid using the legacy syntax for built-in, global, agent, or chain variables, as it's reserved for referencing environment variables in a script.
PulseUno version 23.4: For details about including secrets in chain variables, see Reference secrets in chains.
Example of using an agent variable in a chain:
-
As an administrator, you create a chain that uses Maven and can run on two agents.
Maven is installed in different locations on each agent.
- You add a variable to each agent, MAVEN_HOME, which defines the location of the Maven installation on that agent.
- You add the {{MAVEN_HOME}} variable in the chain step.
- When the chain runs on an agent, the value of the variable is substituted with the value for the Maven location on that agent.
See also: