Built-in Harness Variables Reference

Updated 1 week ago by Michael Cretzman

This topic describes the default (built-in) Harness expressions, as well as the prefixes used to identify user-created variables. This list will be periodically updated when new expressions are added to Harness.

Variable Expression Limitations and Restrictions

Review the following variable expression limitations and restrictions to avoid errors when using variable expressions.

Limitations

  • Harness does not support the Ternary conditional ?: operator from JEXL.
  • Harness permits variables only within their scope. You will not see a variable available in a field where it cannot be used.
  • Do not use hyphens (dashes) in variable names, as some Linux distributions and deployment-related software do not allow them.
  • A variable value (the evaluated expression) is limited to 256 KB.
  • You cannot refer to a Pipeline step's expressions within the same step. For example, if you have an HTTP step with the Id foo you cannot use the expression <+execution.steps.foo.spec.url> to reference the HTTP URL within that step. Put another way, you can only reference a step's settings from a different step.
  • You cannot write scripts within an expression <+...>. For example, the following script will not work:
    if ((x * 2) == 5) { <+pipeline.name = abc>; } else { <+pipeline.name = def>; }

Variable Names Across the Pipeline

Variables names must be unique in the same Stage. You can use the same variable names in different Stages in the same Pipeline or other Pipelines.

Variable Expression Name Restrictions

A variable name is the name in the variable expression, such as foo in <+stage.variables.foo>.

Variable names may only contain a-z, A-Z, 0-9, _. They cannot contain hyphens or dots.

Certain platforms and orchestration tools, like Kubernetes, have their own naming restrictions. For example, Kubernetes doesn't allow underscores. Make sure that whatever expressions you use resolve to the allowed values of your target platforms.

The following keywords are reserved, and cannot be used as a variable name or property:

or and eq ne lt gt le ge div mod not null true false new var return shellScriptProvisioner

See JEXL grammar details.

Harness Variables Basics

Let's quickly review how Harness built-in variable expressions work.

FQNs and Expressions

Everything in Harness can be referenced by a Fully Qualified Name (FQN) expression.

The FQN is the path to a setting in the YAML of your Pipeline:

You can select the expression for a setting or value in the Pipeline editor or execution.

You don't need to build the expression yourself. Harness provides multiple places where you can copy the variable expression.

For example, you can click the copy button in a Pipeline execution to get the expressions of settings and values.

When building a Pipeline in Pipeline Studio, you can copy the FQN of a setting using Variables.

Stage-level and Pipeline-level Expressions

Every section and step in a stage contains input information you can reference as expressions.

Click Variables in the Pipeline to view all the inputs and copy their expressions.

There are two expressions for each input:

  • Stage-level: use this option to reference the input anywhere in its Stage.
  • Pipeline-level: begins with pipeline.stages. Use this option to reference the input anywhere in the Pipeline.

Expression Example

Here is a simple example of a Shell Script step echoing some common variable expressions:

echo "Harness account name: "<+account.name>

echo "Harness comp name: "<+account.companyName>

echo "pipeline executionId: "<+pipeline.executionId>

echo "pipeline sequenceId: "<+pipeline.sequenceId>

echo "stage name: "<+stage.name>

echo "service name: "<+service.name>

echo "service variables: "<+service.variables.example_var>

echo "artifact image: "<+artifact.image>

echo "artifact.imagePath: "<+artifact.imagePath>

echo "environment name: "<+environment.name>

echo "infrastructure connectorRef: "<+infra.connectorRef>

echo "infrastructure namespace: "<+infra.namespace>

echo "infrastructure releaseName: "<+infra.releaseName>

Here is an example of the output:

Harness account name: Harness.io

Harness comp name: Harness.io

pipeline executionId: T4a7uBs7T-qWhNTr-LnFDw

pipeline sequenceId: 16

stage name: dev

service name: nginx

service variables: foo

artifact image: index.docker.io/library/nginx:stable

artifact.imagePath: library/nginx

environment name: quickstart

infrastructure connectorRef: account.harnesstestpmdemocluster

infrastructure namespace: default

infrastructure releaseName: docs

Command completed with ExitCode (0)

Input and Output Variable Expressions

You can reference the inputs and outputs of any part of your Pipeline.

  • Input variable expressions reference the values and setting selections you made in your Pipeline.
  • Output variable expressions reference the results of a Pipeline execution.

You can reference inputs in Pipeline Variables:

Input and Output Variable Expressions in Executions

Inputs and outputs are displayed for every part of the Pipeline execution.

Here's the inputs and outputs for a Kubernetes Rollout Deployment step:

Inputs

Outputs

You can copy the expressions for the names or values of any input or output.

Name

Value

Here are the Name and Value expressions for the podIP setting:

  • Name:
    <+pipeline.stages.Deploy_Service.spec.execution.steps.rolloutDeployment.deploymentInfoOutcome.serverInstanceInfoList[0].podIP>
  • Value: 10.100.0.6

Using Expressions in Settings

You can use Harness variable expressions in most settings.

When you select Expression in a setting, you type <+ and a value and the list of available variables appears:

Simply click a variable expression name to use it as the value for this setting.

At runtime, Harness will replace the variable with the runtime value.

You can also paste in expressions that don't appear. Such as expressions that reference settings in previous Stages.

See Fixed Values, Runtime Inputs, and Expressions.

Only Use Expressions After They'll Be Resolved

When Harness encounters an expression during Pipeline execution, it tries to resolve it with the information it has at that point in the execution. Consequently, you can only use an expression after Harness has the required information. If you try to use an expression before Harness has its information, it will fail.

In this illustration, you can see how the information in each section of the Stage are referenced:

Here's how you reference the information in each of these sections:

  • Service expressions can only be used after Harness has progressed through the Service section of the Pipeline.
    • Service expressions they can be used in Infrastructure and Execution.
  • Infrastructure expressions can only be used after Harness has progressed through the Infrastructure section of the Pipeline.
    • In Infrastructure, you can reference Service settings.
    • Since Execution follows Infrastructure, you can reference Infrastructure expressions in Execution.
  • Execution expressions apply to steps in Execution.
    • Each step's Execution expressions can only be used after Harness has progressed through that step in the Execution section:

Built-in CIE Codebase Variables Reference

In Harness, you set up your Codebase by connecting to a Git repo using a Harness Connector and cloning the code you wish to build and test in your Pipeline.

Harness also retrieves your Git details and presents them in your Build stage once a Pipeline is run.

Using Harness built-in expressions, you can refer to the various attributes of your Codebase in Harness stages.

Here is a simple example of a Shell Script step echoing some common Codebase variable expressions:

echo <+codebase.commitSha>
echo <+codebase.targetBranch>
echo <+codebase.sourceBranch>
echo <+codebase.prNumber>
echo <+codebase.prTitle>
echo <+codebase.commitRef>
echo <+codebase.repoUrl>
echo <+codebase.gitUserId>
echo <+codebase.gitUserEmail>
echo <+codebase.gitUser>
echo <+codebase.gitUserAvatar>
echo <+codebase.pullRequestLink>
echo <+codebase.pullRequestBody>
echo <+codebase.state>

See Built-in CIE Codebase Variables Reference.

Account

<+account.identifier>

The entity identifier of the Harness account.

<+account.name>

Harness account name.

<+account.companyName>

The name of the company for the account.

Org

<+org.identifier>

The entity identifier of an organization.

<+org.name>

The name of the Org.

<+org.description>

The description of the Org.

Project

<+project.name>

The name of the Harness Project.

<+project.description>

The description of the Harness Project.

<+project.tags>

All Harness Tags attached to the Project.

<+project.identifier>

The entity identifier of the Harness Project.

Pipeline

Pipeline-level Variables

Here's a quick video that explains how to create and reference Pipeline, Stage, and Service variables:

<+pipeline.identifier>

The Entity Identifier (Id) for the Pipeline.

<+pipeline.executionId>

Every execution of a Pipeline is given a universally unique identifier (UUID). The UUID can be referenced anywhere.

For example, in the following execution URL the UUID follows executions and is kNHtmOaLTu66f_QNU-wdDw:

https://app.harness.io/ng/#/account/12345678910/cd/orgs/default/projects/CD_Quickstart/pipelines/Helm_Quickstart/executions/kNHtmOaLTu66f_QNU-wdDw/pipeline

<+pipeline.name>

The name of the current Pipeline.

<+pipeline.sequenceId>

The incremental sequential ID for the execution of a Pipeline. A <+pipeline.executionId> does not change, but a <+pipeline.sequenceId> is incremented with each run of the Pipeline.

The first run of a Pipeline receives a sequence ID of 1 and each subsequent execution is incremented by 1.

For CD Pipelines the ID is named Execution. For CI Pipelines the ID is named Builds.

You can use <+pipeline.sequenceId> to tag a CI build when you push it to a repo, and then use <+pipeline.sequenceId> to pull the same build and tag in a subsequent stage. See CI Pipeline Quickstart.

<+pipeline.startTs>

The start time of a Pipeline execution in Unix Epoch format. See Trigger How-tos.

<+pipeline.triggerType>

The type of Trigger. See Trigger How-tos.

<+pipeline.triggeredBy.name>

The name of the user or the Trigger name if the Pipeline is triggered using a Webhook. See Trigger Pipelines using Git Events.

If a user name is not present in the event payload, the <+pipeline.triggeredBy.name> expression will resolve as empty. For example, in the SaaS edition of Bitbucket, a user name is not present.

<+pipeline.triggeredBy.email>

The email of the user who triggered the Pipeline. This returns NULL if the Pipeline is triggered using a webhook. See Trigger How-tos.

Stage

Stage-level Variables

Here's a quick video that explains how to create and reference Pipeline, Stage, and Service variables:

Once you've created a stage, its settings are in the Overview tab. For example, here's the Overview tab for a Deploy stage:

In Advanced, you can add Stage Variables.

Stage variables are custom variables you can add and reference in your stage and Pipeline. They're available across the Pipeline. You can override their values in later stages.

You can even reference stage variables in the files fetched at runtime.

For example, you could create a stage variable name and then reference its identifier in the Kubernetes values.yaml file used by this stage: name: <+stage.variables.name>:

name: <+stage.variables.name>
replicas: 2

image: <+artifact.image>
...

When you run this Pipeline, the value for name is used for the values.yaml file. The value can be a Fixed Value, Expression, or Runtime Input.

You reference stage variables within their stage using the expression <+stage.variables.[variable name]>.

You reference stage variables outside their stage using the expression <+pipeline.stages.[stage name].variables.[variable name]>.

<+stage.name>

The name of the stage where the expression is evaluated.

<+stage.description>

The description of the stage where the expression is evaluated.

<+stage.tags>

The tags on the stage where the expression is evaluated. See Tags Reference.

These tags are different from Docker image tags.

<+stage.identifier>

The entity identifier of the stage where the expression is evaluated.

Service

Service-level Variables

Here's a quick video that explains how to create and reference Pipeline, Stage, and Service variables:

<+serviceConfig.serviceDefinition.spec.variables.[var_name]>

The value of the Service-level variable in [var_name].

Use expression anywhere after the Service step in the Pipeline.

To reference the variables, click the copy button:

There are two options:

  • Copy variable name: use this option if you will only be referencing this variable in the current Stage. Expression:
    • <+serviceConfig.serviceDefinition.spec.variables.[name]>
  • Copy fully qualified name: use this option if you will be referencing this variable in another Stage. Example:
    • <+pipeline.stages.[stage_name].spec.serviceConfig.serviceDefinition.spec.variables.[name]>

You can use these expressions in any setting in your Pipeline. You simply select the Expression option and enter the expression:

To override the Service variable in a script, you simply reference its name and use a new value.

<+service.name>

The name of the Service where the expression is evaluated.

<+service.description>

The description of the Service where the expression is evaluated.

<+service.tags>

The tags on the Service where the expression is evaluated.

To reference a specific tag use <+service.tags.[tag_key]>.

<+service.identifier>

The entity identifier of the Service where the expression is evaluated.

Artifact

If an artifact expression is a manifest or step, you will be prompted to select an artifact at runtime. This is true even if the Stage does not deploy an artifact (such as a Custom Stage or a Stage performing a Kustomize deployment). If you want to reference an artifact that isn't the primary deployment artifact without being prompted, you can use an expression with quotes, like docker pull <+artifact<+".metadata.image">>.

<+artifact.tag>

Not Harness Tags. This expression evaluates to the tags on the artifact pushed, pulled, or deployed. For example, AMI tags, or if you are deploying Docker image nginx:stable-perl then stable-perl is the tag.

<+artifact.image>

The name of the artifact use for the stage.

For example, if you are deploying the public Docker image nginx then nginx:stable-perl at is the output runtime.

Typically you use this expression in the values.yaml to reference the artifact added to Harness.

name: <+stage.variables.name>
replicas: 2

image: <+artifact.image>
# dockercfg: <+artifact.imagePullSecret>

createNamespace: true
namespace: <+infra.namespace>
...

See Add Container Images as Artifacts for Kubernetes Deployments.

<+artifact.imagePath>

The location of the artifact.

For example, if you are deploying the public Docker image nginx then registry.hub.docker.com/library/nginx:stable-perl at is the output runtime.

<+artifact.imagePullSecret>

If some cases, your Kubernetes cluster might not have the permissions needed to access a private Docker registry. For these cases, the values.yaml or manifest file in Service Definition Manifests section must use the dockercfg parameter.

If the Docker image is added in the Service Definition Artifacts section, then you reference it like this: dockercfg: <+artifact.imagePullSecret>.

values.yaml:

name: <+stage.variables.name>
replicas: 2

image: <+artifact.image>
dockercfg: <+artifact.imagePullSecret>

createNamespace: true
namespace: <+infra.namespace>
...

See Pull an Image from a Private Registry for Kubernetes.

<+artifact.type>

The type of repository used to add this artifact in the Service Artifacts. For example, Dockerhub, Ecr, or Gcr.

<+artifact.connectorRef>

The entity identifier for the Connector used to connect to the artifact repo.

Sidecar Artifacts

Sidecar artifact expressions use the Sidecar Identifier to reference the sidecar artifact.

The sidecar identifier is set when you add the sidecar artifact. It can bee seen in the artifact listing:

Here are the sidecar expressions:

  • <+artifacts.sidecars.[sidecar_identifier].imagePath>
  • <+artifacts.sidecars.[sidecar_identifier].image>
  • <+artifacts.sidecars.[sidecar_identifier].type>
  • <+artifacts.sidecars.[sidecar_identifier].tag>
  • <+artifacts.sidecars.[sidecar_identifier].connectorRef>

Environment

<+env.name>

The name of the stage Environment.

<+env.identifier>

The entity identifier of the stage's Environment.

<+env.description>

The description of the Environment.

<+env.type>

The Environment Type, such as Production or Non-Production.

Infrastructure

<+infra.connectorRef>

The name of the Connector used in the Infrastructure Definition.

<+INFRA_KEY>

The infrastructure key. The key is a unique string that identifies a deployment target infrastructure. It is typically used in the Release Name setting to add labels to release for tracking.

For example, in a Deploy stage's Infrastructure Definition, the <+INFRA_KEY> is used in the Release Name to give the release a unique name:

When you deploy, Harness adds the Release Name as a label. For example, in a Kubernetes deployment you can see harness.io/release-name=release-2f9eadcc06e2c2225265ab3cbb1160bc5eacfd4f:

...
Pod Template:
Labels: app=hello
deployment=hello
harness.io/release-name=release-2f9eadcc06e2c2225265ab3cbb1160bc5eacfd4f
Containers:
the-container:
Image: monopole/hello:1
...

Harness can now track the release for comparisons and rollback.

<+infra.namespace>

The namespace used in the Infrastructure Definition.

<+infra.releaseName>

The release name used in the Infrastructure Definition.

Triggers

<+trigger.artifact.build>

Resolves to the artifact version (such as a Docker Tag) that initiated an On New Artifact Trigger.

When you add an On New Artifact Trigger, you select the artifact to listen on and its Tag setting is automatically populated with <+trigger.artifact.build>.

The <+trigger.artifact.build> is used for Tag to ensure that the new artifact version that executed the Trigger is used for the deployment.

When a new tag is added to the artifact, the Trigger is fired and the Pipeline executes. Harness then resolves <+trigger.artifact.build> to the tag that fired the Trigger. This ensures that the new tag is used when pulling the artifact and that version is deployed.

Git Trigger and Payload Expressions

Harness includes built-in expressions for referencing trigger details such as a PR number.

For example:

  • <+trigger.type>
    • Webhook.
  • <+trigger.sourceRepo>
    • Github, Gitlab, Bitbucket, Custom
  • <+trigger.event>
    • PR, PUSH, etc.

For a complete list, see Triggers Reference.

Triggers and RBAC

Harness RBAC is applied to Triggers in Harness, but it is not applied to the repos used by the Triggers.

For example, you might have an On New Artifact Trigger that is started when a new artifact is added to the artifact repo. Or a Webhook Trigger that is started when a PR is merged.

In Harness, you can select who is able to create and use these Triggers within Harness, but you must use your repos' RBAC to control who can add the artifacts or initiate the events that start the Harness Trigger.

Kubernetes

${HARNESS_KUBE_CONFIG_PATH}

The path to a Harness-generated kubeconfig file containing the credentials you provided. The credentials can be used by kubectl commands by exporting its value to the KUBECONFIG environment variable.

You can use this variable in a Shell Script step to set the environment variable at the beginning of your kubectl script:

export KUBECONFIG=${HARNESS_KUBE_CONFIG_PATH}

Tag Expressions

You can reference Tags using Harness expressions.

You simply reference the tagged entity and then use tags.[tag name], like <+pipeline.tags.docs>

For example, here are several different references:

  • <+pipeline.tags.[tag name]>
  • <+stage.tags.[tag name]>
  • <+pipeline.stages.s1.tags.[tag name]>
  • <+serviceConfig.service.tags.[tag name]>

See Also


Please Provide Feedback