Skip to main content
System StatusContact Support Agility Community

Tutorial - Using Variables in Pipelines


This tutorial walks you through the process of using variables in pipelines.

Hopefully you have already explored Tutorial 1: A First Pipeline. If not please start with that tutorial.

Referencing variables in Pipeline Definitions allows you to create single definitions that serve multiple Projects, CI Jobs, repository branches, etc. There really is no limit to how you use and reference variables. However you must first understand how the data is structured and what the syntax is. This was briefly touched on in the first tutorial.

Before a Project Directive or a Pipeline Step is executed, any inputs are run through a variable processor, referenced, and substituted back into the input. Typically the reference may be to data associated with a Change, but it also may be data that was collected from various sources during a Pipeline Instance run and stored with the instance.

Using a Variable in the Pipeline

Continuing on with the tutorial, we will now use a variable in our tutorial pipeline definition.

Edit the Project created in the first tutorial. On the Details tab, in the Globals box, place the following JSON.

{"job_name": "jenkinsjob"}

Where "jenkinsjob" is the the Jenkins job name used in Tutorial 1.

Now edit the Stage created in Tutorial 1. Replace the job name in the Job box of the Jenkins step with the following:

[$ projectglobals["job_name"] $]

And perform another commit / push to your repository. This should trigger the same Jenkins job as it did in the first tutorial but using a variable in place of the job name. Why would this be useful? One use case would be so that the same Pipeline Definition can serve multiple source Projects but possibly different CI Jobs.

Essentially Global variable settings can be defined on a Project and referenced during a Pipeline Instance run.

For a more detailed explanation of the variable syntax see the variable documentation page.

Referencing Pipeline Instance Data

Much of the data that will need to be used during a Pipeline Instance will be more dynamic than global variables on the Project. For instance one use case may be to pass in the branch name from the Change record and triggered the pipeline. This data will come from the repository commit which will automatically get added to the Pipeline Instance data record.

Before we go on, let's explore the Pipeline Instance data record. In Flow, click on the pipelines menu link at the top. Next select the Instance: to display the Pipeline Instance detail page. Select the Data tab on the left.

This is a view of the data that is associated with the Pipeline Instance. As a Pipeline Instance executes through it's Phases, Stages and Steps this data may get changed and grow. All of this data is can be referenced by variables.

Passing in a Branch to Jenkins

Modify the Jenkins job to accept a text parameter named "BRANCH". Now modify the Jenkins step in the Flow Pipeline Defition to pass in the branch in the Additional Arguments section so that it now reads as follows:

{"params": {"PARAM1": " world", "BRANCH": "[$ __LASTCHANGE['branch'] $]"}}

The "__LASTCHANGE" syntax allows for populating variable from the uniform change data that is associated with the Pipeline Instance. Perform another commit and verify that the branch parameter was passed correctly to the Jenkins job.

Now the branch name can be passed to the Jenkins job and the job can be configured to check out the correct branch to build.


This was a brief intro to variable usable. Again see the variable documentation page for more specifics on referencing variables and some constants that can be used.

Next up we will explore retrieving the results of the Jenkins job and using those results.