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.

Back to top

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.

Back to top

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.

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: