Built-in and custom Harness variables reference
For most settings in Harness pipelines, you can use fixed values, runtime inputs, or expressions.
You can use expressions (also called Harness expressions, variable expressions, or sometimes Harness variables) to reference Harness input, output, and execution variables. These variables represent settings and values that exist in the pipeline before and during execution. These can include environment variables, secrets, pipeline/stage/step identifiers, and more.
This topic describes some built-in and custom Harness expressions, as well as the prefixes used to identify user-created variables.
Expressions are powerful and offer many options for modification or interaction. For more information about using expressions, go to:
- Write expressions using any JSON parser tool
- Use Java string methods
- Expression status type reference
- Add variables
What is a Harness variable expression?
Harness variable expressions refer to a value in Harness, such as an entity name or a configuration setting. At pipeline runtime, Harness evaluates any expressions present in the pipeline and replaces them with the resolved value.
For example, the expression <+pipeline.name>
resolves to name of the pipeline where you're using that expression.
Harness variables are powerful because they enable templatizing of configuration information, pipeline settings, values in scripts, and more. They also enable your pipelines to pass information between stages and settings.
Pipelines won't run if the default value of variables start with *
. You can use *
within " "
as a workaround.
Expression usage
Harness variables are declared as expressions using the expression delimiter <+...>
, such as <+pipeline.name>
or <+secrets.getValue("someSecret")>
.
- Visual
- YAML
In the Pipeline Studio's Visual Editor, you can use the Value type selector to select Expression.
Harness provides suggestions for built-in expressions as you type. You can manually trigger the suggestions by placing your cursor after <+
and pressing ctrl + space
.
In free-text fields, such as Command, you can directly enter values using the appropriate syntax without changing the value type.
You can continue typing or select the expression from the list of suggestions.
When writing pipelines in YAML, enter the expression as the value for a field.
For example, this expression references a pipeline variable named myConnector
.
connectorRef: <+pipeline.variables.myConnector>
When you type <+
, Harness provides suggestions for built-in expressions as you type. You can manually trigger the suggestions by placing your cursor after <+
and pressing ctrl + space
.
You can continue typing or select the expression from the list of suggestions.
Mechanically, Harness passes the content within the delimiter (<+...>
) to the Java Expression Language (JEXL) for evaluation.
You can use JEXL methods to build complex variable expressions. For example, here is a complex expression that uses information from a webhook trigger payload:
<+<+trigger.payload.pull_request.diff_url>.contains("triggerNgDemo")> || <+trigger.payload.repository.owner.name> == "wings-software"
Harness pre-populates many variables, as documented below, and you can set your own variables in the form of context output from shell scripts and other steps.
Java string methods
You can use any Java string method on Harness variable expressions.
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 use the expression in nearly any setting in the pipeline editor.
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 output 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
You can create variables at the pipeline and stage level and reference them using the FQN expressions within their scope.
Click Variables in the pipeline to view all the inputs and copy their expressions.
The pipeline and stage level variable expressions follow these formats:
- Pipeline-level expressions use the format
<+pipeline.variables.VAR_NAME>
. - Stage-level expressions use these formats:
- Use in this stage: Use this option to reference the input anywhere in its stage. The format is
<+stage.variables.VAR_NAME>
. - Use anywhere in the pipeline: Use this option to reference the input anywhere in the pipeline. The format is
<+pipeline.stages.STAGE_NAME.VAR_NAME>
.
- Use in this stage: Use this option to reference the input anywhere in its stage. The format is
- Pipeline-level variables can be accessed as a collection of key-value pairs using
<+pipeline.variables>
. - Stage-level variables can be accessed as a collection of key-value pairs using
<+stage.variables>
.
Expression examples
Here is an 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: "<+serviceVariables.example_var>
echo "artifact image: "<+artifacts.primary.image>
echo "artifact image path: "<+artifacts.primary.imagePath>
echo "environment name: "<+env.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 image path: library/nginx
environment name: quickstart
infrastructure connectorRef: account.harnesstestpmdemocluster
infrastructure namespace: default
infrastructure releaseName: docs
Command completed with ExitCode (0)
Here is another example of how to use <+stage.variables>
.
for var in <+stage.variables>;
do
IFS=":"
read -r key value <<< "$var"
unset IFS
echo "Key: $key"
echo "Value: $value"
done
The above Bash script prints all the key-value pairs for the stage variables.
If the <+stage.variables>
is {"a":"A","b":"B","c":"C"}
then the output will be as follows:
Executing command ...
Key: a
Value: A
Key: b
Value: B
Key: c
Value: C
Command completed with ExitCode (0)
Input and output variables
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's execution.
Input variables in the pipeline
You can copy and reference the input settings for steps using the pipeline Variables panel.
Input variables follow this format:
- Stage-level:
<+execution.steps.STEP_ID.SETTING>
. - Pipeline-level:
<+pipeline.stages.STAGE_ID.spec.execution.steps.STEP_ID.SETTING>
.
Pipeline and stage custom variable expressions use the variable name to reference the variable. The execution step variables use the stage/step identifier (ID) in references.
Input and output variable expressions in executions
Inputs and outputs are displayed for every part of the pipeline execution.
Here are 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.k8s_deployment.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 the Expression option for a setting, you can type <+
and the list of available variable expressions appears.
Select a variable expression to use it as the value for this setting.
At runtime, Harness will replace the variable with the runtime value.
You can also paste expressions that don't appear. For example, expressions that reference settings in previous stages.
For more information, go to Fixed Values, Runtime Inputs, and Expressions.
Expression guidelines and boundaries
Review the following guidelines to avoid errors when using variable expressions.
Scope
When Harness automatically presents variable expressions in a setting, it only exposes the expressions that can be used in that setting. You will not see a variable expression available in a setting where it cannot be used.
This does not prevent you from trying to use an expression outside of its scope.
Here are some guidelines to help you use expressions successfully:
- Don't refer to a step's expressions within the same step.
- Don't refer to the settings for a subsequent step in a previous step.
- Don't refer to inputs or outputs of a stage's Execution tab in the stage's Service or Environment tabs.
- The execution takes place after the service and environment settings are used. Consequently, the expressions used in the execution cannot be resolved when running the service and environment sections.
You can reference the environment name variable, <+env.name>
, in a service's Values YAML file, specs, and config files.
Only use expressions after they can be resolved
When Harness encounters an expression during pipeline execution, it tries to resolve the expression with the information it has at that point in the execution. Consequently, your pipelines can use expressions only after Harness has the required information to resolve the expression's value. If you try to use an expression before Harness has the necessary information, the expression resolves to null and the pipeline can fail or execute incorrectly.
Demonstration of Harness expression resolution in a CD stage
This example demonstrates when and where certain expressions (by prefix) are resolved over the duration of a CD stage, so that you can determine which events need to occur before you can safely reference a certain expression and ensure that it is successfully resolved when the pipeline runs.
Here's when you can reference expressions resolved from information in each of these stage sections:
- Service expressions can be resolved only after Harness has progressed through the Service section of the pipeline. Consequently, you can use service expressions in the Infrastructure and Execution sections of the stage.
- Infrastructure expressions can be resolved only after Harness has progressed through the Infrastructure section of the pipeline.
- In the Infrastructure section, 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 be referenced only after Harness has progressed through that step in the Execution section.
CI stage initialization fails with a "null value" error
If a Build (CI
) stage fails at initialization with a "null value" error, this can indicate that an expression was called before its value could be resolved. For more information, go to Initialize step fails with a "null value" error.
Variable expressions in conditional execution settings
Stages and steps support variable expressions in the JEXL conditions of their Conditional Execution settings.
You can only use variable expressions in the JEXL conditions that can be resolved before the stage is run.
Conditional execution settings are used to determine if the stage should be run, and therefore you cannot use variable expressions that can't be resolved until the stage is run.
For more information on conditional execution, go to Define conditional executions for steps and stages.
Variable value size
A variable value (the evaluated expression) is limited to 256 KB.
Expressions not allowed in comments of Values YAML or Kustomize patches
You cannot use Harness expressions in comments in:
- Values YAML files (values.yaml) in Kubernetes, Helm chart, or Native Helm deployments.
- Kustomize patches files.
For example, here is a values.yaml file with a Harness expression in the comment:
name: test
replicas: 4
image: <+artifacts.primary.image>
dockercfg: <+artifacts.primary.imagePullSecret>
createNamespace: true
namespace: <+infra.namespace>
# using expression <+infra.namespace>
This values.yaml file will not process successfully. Remove any expressions from comments and the file will process successfully.
Scripts within expressions
You cannot write scripts in expressions. For example, the following script will not work:
if ((x * 2) == 5) { <+pipeline.name = abc>; } else { <+pipeline.name = def>; }
Instead, feed the expression value into a variable and then call the variable in your script.
NAME = <+pipeline.name>
if ((x * 2) == 5) { $NAME = abc; } else { $NAME = def; }
Variable name uniqueness
When defining variables at the stage level, variable names must be unique within that stage. You can use the same variable names in different stages of the same pipeline or other pipelines, but not within the same stage.
Avoid hyphens in variable names
Harness recommends not using hyphens/dashes (-
) in variable names, because these characters can cause issues with headers and they aren't allowed in some Linux distributions and deployment-related software.
For example, this expression won't work: <+execution.steps.httpstep.spec.headers.x-auth>
.
If you must reference a variable name that has a hyphen, such as x-auth
, you can wrap the variable name in double quotes (""
), such as <+execution.steps.httpstep.spec.headers["x-auth"]>
.
This also works for nested expressions, such as:
<+execution.steps.httpstep.spec.newHeaders["x-auth"]["nested-hyphen-key"]>
<+execution.steps.httpstep.spec.newHeaders["x-auth"].nonhyphenkey>
When referencing your custom variables, you need to use the get()
method, as explained in Special characters in custom variables can required escaping or additional handling.
Special characters in custom variables can require escaping or additional handling
When you add a variable, note the following restrictions and considerations for variable names:
- Variable names must start with a letter or underscore (
_
). - Variable names can contain lowercase and uppercase letters, numbers 0-9, underscores (
_
), periods (.
), hyphens/dashes (-
), and dollar signs ($
). - Variable names can't contain reserved words.
- Periods and hyphens require additional escaping when referencing those variable names in Harness expressions, such as
foo
in<+stage.variables.foo>
. This handling is explained below. - Additional variable naming restrictions can apply depending on the platforms and tools you use. For example, Kubernetes doesn't allow underscores. Ensure that your expressions resolve to the allowed values of your target platforms.
Use get() for custom variable names with hyphens and periods
Harness recommends avoiding hyphens in variable names.
However, if you need to reference a custom variable that includes a period or hyphen/dash in the name, you must wrap the variable name in double quotes and use the get()
method in the expression, such as .get("some-var")
.
For example:
<+pipeline.variables.get("pipeline-var")>
<+pipeline.stages.custom.variables.get("stage-var")>
<+pipeline.variables.get("pipeline.var")>
<+pipeline.stages.custom.variables.get("stage.var")>
This handling is also required for matrix dimension names with hyphens.
Reserved words
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
class
For more information, go to JEXL grammar details.
Number variables
Number type variables are always treated as doubles (double-precision floating-point).
- -1.79769313486231E308 to -4.94065645841247E-324 for negative values.
- 4.94065645841247E-324 to 1.79769313486232E308 for positive values.
For example, here is a pipeline variable of number type.
variables:
- name: double_example
type: Number
description: ""
value: 10.1
The expression to reference that pipeline variable, <+pipeline.variables.double_example>
, will be treated as a double when it is resolved to 10.1
.
Numbers as doubles and strings
Whether the number in a variable is treated as a double or string depends on the field that you use it in.
If you enter 123
in a string setting, such as a Name, it is treated as a string. If you enter 123
in a count setting, such as Instances, it is treated as a double.
Contains method
When using contains
, ensure the expression is wrapped within <+ >
and the specific string is within "
.
For example, <+<+stage.name>.contains("s1")>
.
Split method
When using split
, ensure the expression is wrapped within <+ >
.
For example, <+<+pipeline.variables.abc>.split(':')[1]>
.
Complex expression
When using a complex expression, ensure the expression is wrapped within <+ >
.
For example:
<+ <+<+trigger.payload.pull_request.diff_url>.contains("triggerNgDemo")> || <+trigger.payload.repository.owner.name> == "wings-software">
Ternary operator
When using ternary conditional ?:
operators, do not use spaces between the operators and values. Ensure the expression is wrapped within the expression delimiter <+ >
.
When you evaluate Harness expressions using any operator (including ternary operators), the expression values must be available for resolution at the time of the evaluation.
For example, if you use an expression for the value of a pipeline stage step setting, such as <+pipeline.stages.mystage.spec.execution.steps.myapplystep.executionUrl>
, ensure that the evaluation using that expression happens after the step myapplystep
has run.
Ternary operators in Harness follow the standard format, but you cannot use spaces between the operators and values.
For example, <+condition ? <value_if_true> : <value_if_false>>
will not work.
Use <+condition?<value_if_true>:<value_if_false>>
instead.
Ensure the expression is wrapped within <+ >
:
<+condition?<value_if_true>:<value_if_false>>
Pipeline example
Here's a simple Harness YAML pipeline example of evaluating a Harness variable value with the ternary operator:
pipeline:
name: exp
identifier: exp
projectIdentifier: CD_Docs
orgIdentifier: default
tags: {}
stages:
- stage:
name: ternarydemo
identifier: ternarydemo
description: ""
type: Custom
spec:
execution:
steps:
- step:
type: ShellScript
name: ShellScript_1
identifier: ShellScript_1
spec:
shell: Bash
onDelegate: true
source:
type: Inline
spec:
script: echo <+stage.variables.myvar>
environmentVariables: []
outputVariables: []
timeout: 10m
- step:
type: ShellScript
name: ternary
identifier: ternary
spec:
shell: Bash
onDelegate: true
source:
type: Inline
spec:
script: echo <+ <+stage.variables.myvar> == "1.1"?"this is right":"this is wrong" >
environmentVariables: []
outputVariables: []
timeout: 10m
tags: {}
variables:
- name: myvar
type: String
description: ""
required: true
value: "1.1"
In this example, there is a stage variable named myvar
with a value of 1.1
. In the ShellScript
step named ternary
the variable expression for the stage variable, <+stage.variables.myvar>
, is evaluated with the ternary expression:
<+ <+stage.variables.myvar> == "1.1"?"this is right":"this is wrong" >
Ternary operators are also discussed in the Harness Knowledge Base.
Equals operator
When using the ==
operator, ensure the expression is wrapped within <+ >
.
For example, <+<+pipeline.name> == "pipeline1">
or <+<+stage.variables.v1> == "dev">
.
Greater than and Less than operators are not supported for string expression types. Only Equal to and Not equal to are supported.
Variable concatenation
Harness string variables can be concatenated by default. Each expression can be evaluated and substituted in the string.
Previously, Harness users were forced to use a ‘+’, or .concat()
, the concatenation operator, to join multiple expressions together. Now, you can simply use <+pipeline.name> <+pipeline.executionId>
.
For example, Harness supports complex usages such as the following:
us-west-2/nonprod/eks/eks123/<+env.name>/chat/
<+stage.spec.execution.steps.s1<+strategy.identifierPostFix>.steps.ShellScript_1.output.outputVariables.v1>
- This example uses the index of the looped execution to pick the correct step.
<+pipeline.stages.<+pipeline.variables.stagename>.status>
- This example shows an elegant way to print out the status of a stage.
All existing expressions will continue to work. For example, the following syntax will still work.
- Use
+
operator to add string value variables:<+<+pipeline.variables.var1> + "_suffix">
. - Use Java
concat
method to add string variables:
<+<+pipeline.variables.var1>.concat("_suffix")>
Ensure the expression is wrapped within <+ >
in both of these examples.
When concatenating expressions as strings, each expression must evaluate to a string.
If an expression does not satisfy this condition, use the toString()
method to convert it to a string.
For example, in /tmp/spe/<+pipeline.sequenceId>
the variable sequenceId
evaluates to an integer. When concatenating this with other string expressions, it must be converted to a string, such as: /tmp/spe/<+pipeline.sequenceId.toString()>
Passing JSON values using variables
When using expressions in JSON as a string, they must be wrapped in quotation marks for valid JSON.
For example, consider the following JSON:
"{\"a\":[ { \"name\": \"svc1\", \"version\": \"<+pipeline.variables.version>\", \"hosts\": <+<+pipeline.variables.hosts>.split(\",\")> } ]}"
In the JSON above, the expression <+pipeline.variables.version>
must be wrapped in quotation marks because it resolves as a string inside JSON (and Strings need to be quoted). The expression <+<+pipeline.variables.hosts>.split(\",\")>
doesn't need to be wrapped in quotation marks because it will be resolved as a list.
Let's look at an example using allowed values and JSON strings.
A variable with <+input>.allowedValues({"x":"y"})
and "<+input>.allowedValues({x:y})"
have the same value, which is {x:y}
. You can add space in the second example, "<+input>.allowedValues({x: y})"
to get {x: y}
and it doesn't cause any errors.
You can do this with quotes as well. For example, "<+input>.allowedValues({\\\"x\\\": \\\"y\\\"})"
produces {"x": "y"}
.
Best practices for expressions usage
-
When using an expression, if you want to treat it as a string, you must wrap it within quotation marks.
For example, consider following expression:
<+<+pipeline.variables.changeType> =~ ["<+stage.name>","All"]>
In the above expression, the
<+stage.name>
is wrapped within quotation marks because it is an element in a list of strings. -
While using
,
inside a method invocation with an expression, the expression must be wrapped in quotation marks.For example, consider the following expression:
<+<+pipeline.variables.var2>.replace("a", "<+pipeline.variables.var1>")>
In the above expression,
<+pipeline.variables.var1>
must be wrapped in quotation marks because the expression is a string parameter for a method. -
While using method invocation with an expression, the expression before method invocation should also be wrapped within
<+...>
.For example, consider the following expression:
<+<+pipeline.variables.var1>.concat("concatenating a string")>
To invoke the method
concat
on the expression<+pipeline.variables.var1>
, you must wrap<+pipeline.variables.var1>
within<+...>
and then invoke the method using.concat()
. -
When using an expression for the Harness secret functor,
<+secrets.getValue("sec")>
, it should not be wrapped within quotation marks.This expression gets resolved to another Harness internal functor,
${ngSecretManager.obtain("sec")}
, which is resolved on the delegate. Since its value is not a primitive type string, it should not be wrapped within quotation marks.For example, consider the following expression for the value of a pipeline or stage variable:
<+<+<+pipeline.variables.var1>=="secret1">?<+secrets.getValue("secret1")>:<+secrets.getValue("defaultSecret")>>
This secret expression should not be wrapped within quotation marks.
-
If expressions don't need to be evaluated in the pipeline YAML but are added as script comments in the Shell Script step, the Run step, or another step, they will still be processed and evaluated. This might cause failures and unnecessary processing. Review and remove any unnecessary script comments from the pipeline YAML to streamline the evaluation process.
-
Usage of
getClass()
in expressions is not supported and will not be evaluated.
Debugging expressions
An easy way to debug expressions in your pipeline is to use Compiled Mode in your Variables panel. You can enable this mode using a radio button at the top of the Variables Panel. When Compile Mode is turned on, all of the expressions in the panel are compiled and their values are displayed. By default, the compilation happens against the pipeline's latest execution. You can change this by selecting from a displayed list of previous executions.
Expressions that are incorrect or cannot be evaluated using the execution data are highlighted in the Variable values column. You can switch the panel back to normal mode and correct the expression.
To test an expression that isn't part of a variable (say, something in a script), you can create a temporary variable in the panel, assign the expression to it, and use Compiled Mode to debug it.
CI codebase and environment variables
You can use Harness expressions to reference various environment variables and codebase attributes in Harness CI pipelines, stages, and steps. For more information, go to:
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.
Custom account variables
For more information, go to Add Account, Org, and Project-level Variables.
Org
<+org.identifier>
The entity identifier of an organization.
<+org.name>
The name of the org.
<+org.description>
The description of the org.
Custom org variables
For more information, go to Add Account, Org, and Project-level Variables.
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.
Custom project variables
For more information, go to Add Account, Org, and Project-level Variables.
Pipeline
Pipeline-level variables
Here is a quick video that explains how to create and reference pipeline, stage, and service variables.
<+pipeline.identifier>
The 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.executionUrl>
The execution URL of the pipeline. This is the same URL you see in your browser when you are viewing the pipeline execution.
For example:
https://app.harness.io/ng/#/account/12345678910/cd/orgs/default/projects/CD_Docs/pipelines/Triggers/executions/EpE_zuNVQn2FXjhIkyFQ_w/pipeline
The version of this expression with an additional period, <+pipeline.execution.Url>
, has been deprecated.
<+pipeline.executionMode>
This expression describes the pipeline's execution mode:
NORMAL
: A normal execution. It could either have succeeded or failed.POST_EXECUTION_ROLLBACK
: A post-deployment rollback execution.PIPELINE_ROLLBACK
: A rollback pipeline execution.
You can use this expression in conditional executions.
For example, you can create a conditional execution to ensure that a step runs only when a post-deployment rollback happens. Here's an example of the logs for this conditional execution scenario:
<+pipeline.name>
The name of the current pipeline.
<+pipeline.sequenceId>
The incremental sequential Id for the execution of a pipeline. A <+pipeline.executionId>
is randomly generated for each execution, 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 repository, and then use <+pipeline.sequenceId>
to pull the same build and tag in a subsequent stage. For examples, go to Build and test on a Kubernetes cluster build infrastructure tutorial and Integrating CD with other Harness modules.
<+pipeline.startTs>
The start time of a pipeline execution in Unix Epoch format. For more information, go to Triggers.
<+pipeline.triggerType>
The type of trigger. For more information, go to Triggers.
Here are the possible <+pipeline.triggerType>
and <+trigger.type>
values.
<+pipeline.triggerType> | <+trigger.type> | Description |
---|---|---|
ARTIFACT | Artifact | New artifact trigger. For example, new Docker Hub image tag |
SCHEDULER_CRON | Scheduled | Scheduled Cron trigger |
MANUAL | null | Pipeline triggered using the RUN button in the user interface |
WEBHOOK_CUSTOM | Custom | Custom webhook trigger |
WEBHOOK | Webhook | SCM webhook trigger. For example, GitHub pull request |
<+pipeline.triggeredBy.name>
The name of the user or the trigger name if the pipeline is triggered using a webhook. For more information, go to 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. For more information, go to Trigger How-tos.
<+pipeline.selectedStages>
The list of stages selected for execution.
<+pipeline.delegateSelectors>
The pipeline level delegate selectors selected via runtime input.
<+pipeline.storeType>
If the pipeline is stored in Harness, the expression resolves to inline
. If the pipeline is stored in a Git repository, the expression resolves to remote
.
<+pipeline.repo>
For remote pipelines, the expression resolves to the Git repository name. For inline pipelines, the expression resolves to null
.
<+pipeline.branch>
For remote pipelines, the expression resolves to the Git branch where the pipeline exists. For inline pipelines, the expression resolves to null
.
Deployment, pipeline, stage, and step status
Deployment status values are a Java enum. You can see the list of values in the deployments Status filter:
You can use any status value in a JEXL condition. For example, <+pipeline.stages.stage1.status> == "FAILED"
.
Stage status
The expression <+pipeline.stages.STAGE_ID.status>
resolves to the status of a stage.
You must use the expression after the stage in execution.
Step status
The expression <+pipeline.stages.STAGE_ID.spec.execution.steps.STEP_ID.status>
resolves to the status of a step. For example, <+pipeline.stages.MyStageName.spec.execution.steps.mystep.status>
.
You must use the expression after the step in execution.
InputSet
Displays the Input Set values for the execution as a JSON value. The list of values can be searched via <+inputSet>
.
Here's an example where the Timeout settings for the two steps preceding the step using <+inputSet>
are using values from an Input Set:
{pipeline:identifier:Custom} {pipeline:stages:[{stage:identifier:Custom}]} {pipeline:stages:[{stage:type:Custom}]} {pipeline:stages:[{stage:spec:{execution:steps:[{step:identifier:ShellScript_1}}}]} {pipeline:stages:[{stage:spec:{execution:steps:[{step:type:ShellScript}}}]} {pipeline:stages:[{stage:spec:{execution:steps:[{step:timeout:10s}}}]} {pipeline:stages:[{stage:spec:{execution:{step:identifier:json_format}]}}]} {pipeline:stages:[{stage:spec:{execution:{step:type:ShellScript}]}}]} {pipeline:stages:[{stage:spec:{execution:{step:timeout:10m}]}}]}
Stage
The following variables provide information on the pipeline stage.
Stage-level variables
Here is 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 is 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: <+artifacts.primary.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. For more information, go to Tags Reference.
These tags are different from Docker image tags.
<+stage.identifier>
The entity identifier of the stage where the expression is evaluated.
<+stage.output.hosts>
Lists all of the target hosts when deploying to multiple hosts.
When you are deploying to multiple hosts, such as with an SSH, WinRM, or deployment template stage, you can run the same step on all of the target hosts.
To run the step on all hosts, you use the repeat Looping Strategy and identify all the hosts for the stage as the target.
repeat:
items: <+stage.output.hosts>
Here is an example with a Shell script step.
For examples, see the looping strategies used in the Secure Shell (SSH) deployments.
<+stage.executionUrl>
The execution URL of the stage. This is the same URL you see in your browser when you are viewing the pipeline execution.
Use the following fully qualified expression to get the execution URL for a specific stage in the pipeline:
<+pipeline.stages.STAGE_ID.executionUrl>
<+stage.delegateSelectors>
The stage level delegate selectors selected via runtime input
Service
Currently, there are two versions of services and environments, v1 and v2. Services and environments v1 are being replaced by services and environments v2.
The use of variable expressions is different between v1 and v2.
For more information, go to Services and Environments Overview.
Service-level variables for service v2
To reference a service variable, use the expression <+serviceVariables.VARIABLE_NAME>
.
For example, <+serviceVariables.myvar>
.
Service-level variables for service v1
Here is 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. Select the expression option and enter the expression.
To override the service variable in a script, reference its name and use a new value.