Share this page

# 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.

In this topic:

## Variable types

You can use chain, agent, and global variables in chain steps. There is also a set of native built-in variables to include in chains.

The following table describes the variable types.

Type | Description
--- | ---
Built-in variables | Native 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, the value of the chain variable is used. 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, the value of the chain variable is used. 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, the value of the agent or chain variable is used. Chain variables override agent or global variables that have the same names. For details, see Define chain and global variables.

Back to top

## Built-in variables

You can use the following native 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: The value is displayed 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. The value is displayed 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. The username and password values are generated automatically when a chain is triggered, and invalidated 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.

Back to top

## Reference variables in chains

To reference variables in chain steps, use the following syntax: {{variable_name}}

Caution: The legacy syntax ${variable_name} is also recognized. 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.

For details about including secrets in chain variables, see Reference secrets in chains.

Example of using an agent variable in a chain:

1. 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.

2. You add a variable to each agent, MAVEN_HOME, which defines the location of the Maven installation on that agent.
3. You add the {{MAVEN_HOME}} variable in the chain step.
4. When the chain runs on an agent, the value of the variable is substituted with the value for the Maven location on that agent.

Back to top

See also:

- Manage agents
- Run chains

https://admhelp.microfocus.com PulseUno 8942
Tips to improve your search results... PulseUno Help Center PulseUno Help 24.2 - 25.2 All View Local Help Center View Online Help Center Version: