Passing Variables into Workflows and Pipelines from Triggers

Updated 3 weeks ago by Michael Cretzman

You can pass variables from a Harness Trigger into a Harness Workflow to be used during Workflow steps or configuration, or as part of a Pipeline. This process can be valuable when you want to use information from the condition that initiated the Trigger as settings in your Workflow at runtime.

An example is using a Github or Bitbucket push or pull request as a Trigger condition and passing push or pull request information to a Workflow via the Trigger. In the Workflow, you could take the branch name from the push or pull request and use it to create a namespace in a Helm chart, thereby creating a new Kubernetes namespace for each branch during deployment.

The Workflow can be made into a template (templatized) and each dev that has a branch on the repo can initiate the Trigger with a push or pull request. For more information on using Workflows as templates, see Template a Workflow.

Passing Variables Overview

To pass variables from a Trigger into a Workflow, perform the following steps:

  1. Create a Workflow.
  2. Add one or more Workflow variables to the Workflow.
  3. Use the variables in your Workflow steps or configuration.
  4. Create a Trigger.
  5. Select the Trigger condition, such as a Git pull request.
  6. Select your Workflow as the target for the Trigger. This will expose the Workflow variables in your Trigger.
  7. In the Trigger, use variable values from the Trigger condition to define the Workflow variables, such as values passed in from the Git pull request.
  8. Use the Trigger URL to initiate the Trigger. For example, add the Trigger URL to the Git repo as a Webhook.

These steps are demonstrated in detail below.

Intended Audience

  • Developers
  • DevOps

Before You Begin

Set Up Workflow with Variables

The following procedure creates Workflow variables in an existing Workflow.

To set up Workflow variables, do the following:

  1. In a Workflow, click the pencil icon next to Workflow Variables.

    The Workflow Variables dialog appears.

    The Workflow Variables dialog has the following fields.

    Field

    Description

    Variable Name

    Enter a name for the variable. When the variable is used in a Trigger or elsewhere in the Harness Application, the variable name is used.

    The syntax for variable names is ${workflow.variables.name}. For example, if you created a variable named Url, the variable name is ${workflow.variables.Url}.

    Type

    Select the data type, such as TextNumber, or Email. For using the variables in Triggers, select Text.

    Default Value

    Enter a value for the variable. A value is not mandatory. If you will be placing a value in the variable via a Trigger, you will typically leave Default Value empty.

    Required

    Select this option to enforce that a value for the variable is provided before the Workflow is executed.

    Fixed

    Select this option if the value of the variable specified here must not be changed. If you will be placing a value in the variable via a Trigger, you will not enable Fixed.

    Description

    Provide a description of the variable that lets others know its purpose and requirements.

  2. When you have added your variables, click SUBMIT. The Workflow Variables section of the Workflow displays the new variables.
  3. Use the variables in your Workflow. For example, if you added a variable name Environment and you want to use it to set the Workflow Environment setting, you would use ${Environment} in the Workflow settings.
  4. Next, create a Trigger to execute this Workflow and provide a value for the ${Environment} variable, as described below.

Populate Workflow Variables in a Trigger

The following procedure creates a Trigger that executes a Workflow and populates its Workflow variables. In this example, we use Git push information to populate the variables.

To create a Trigger that populates Workflow variables, do the following:

  1. Click Setup.
  2. Click the Application that contains the Workflow or Pipeline you want to Trigger.
  3. Click Triggers.
  4. Click Add Trigger. The Trigger dialog appears.
  5. In Name, enter name for the Trigger that helps others understand its function, and click Next.
  6. In Condition, select the condition that will execute the Trigger. The actions available to the Trigger depend on which condition you select. For this example, click On Webhook Event.
  7. In Repository Type, click Github or BitBucket. The variables you can enter in Actions depend on which Git provider you select.
  8. In Event Type, select On Push. The event type you select determines what variables you can use in Actions.
  9. In Action, select Open or leave it blank.
  10. Click Next. The Actions settings appear.
  11. In Execution Type, select Workflow. You can also select Pipeline. If you select Pipeline, the Workflow variables for all of the Workflows in the Pipeline will be available.
  12. In Execute Workflow. select the Workflow you created. The Workflow Variables section displays the variable you defined in the Workflow.
  13. For the Workflow variable, such as the Environment variable example, click in the Value field. The drop-down will list the environments configured in your Application. If you scroll to the bottom of the list you will see custom values.

    These are the builtin variables you can use to obtain information from the Git push.
  14. Select a variable to use. For example, if you had a Harness environment named after each Git branch and you wanted to use the name of a Git branch to pick the matching environment, you could select the variable named ${ref.split(‘/’)[2]} to obtain the branch name.
    Whenever you specify an environment you also have to specify a service infrastructure. Consequently, if you want to set an environment with a variable, you will likely need to set the service infrastructure with a variable, also.
  15. When you are done, click Next, and then click SUBMIT.

The final step is to take the Trigger's Github Webhook URL and add it to your repo.

  1. In Triggers, in the listing for your Trigger, click Github Webhook (or Bitbucket Webhook).
  2. Copy the URL and use it in Github to execute the Trigger. Ensure the Webhook pushes and pull requests events are selected in your repo.

Push and Pull Request Variables

The following list of Git push and pull request variables are available in a Trigger, and can be passed to the Workflows (and Pipelines) executed by the Trigger.

For information on any of the values in the GitHub or Bitbucket response payload, see the GitHub REST API V3 and Bitbucket API. You can see an example payload from GitHub at Webhook payload example.

Variables

Description of Values

${ref}

Obtain the ref string from the push or pull request.

${ref.split(‘/’)[2]}

Splits a ref string into its substrings based on the / delimiter and limits the number of strings returned to two. For more information on the Java split() method see split in the Java docs.

${commits[0].id}

Commit ID of commit.

${head_commit.id}

Head ID of commit.

${repository.name}

Repo name.

${repository.id}

Repo ID.

${pullrequest.id}

Pull request ID. For example: "id": 222571186.

${pullrequest.title}

Output title.

${pullrequest.fromRef.branch.name}

The head branch where the changes are on.

${pullrequest.toRef.branch.name}

The branch where the changes will be merged.

${pullrequest.fromRef.repository.project.name}

The repo project where the changes are on.

${pullrequest.toRef.repository.project.name}

The repo project where the changes will be merged.

${pullrequest.fromRef.repository.owner.username}

The username for the repo where the changes are on.

${pullrequest.toRef.repository.owner.username}

The username for the repo where the changes will be merged.

${pullrequest.fromRef.commit.hash}

The merge_commit_sha for the commit from the branch.

${pullrequest.toRef.commit.hash}

The merge_commit_sha for the commit to the merged branch.

You can also add text before and after the variable.

Passing Variables Along a Pipeline

When you have multiple Workflows in a Pipeline, you can pass variables into each Workflow in the pipeline via the Trigger for the Pipeline, and you can pass in variables to be used in every workflow in the pipeline.

For example, let's say you wanted all the Workflows in a Pipeline to use the same Environment and Service Infrastructure, and the names of the Environment and Service Infrastructure are based on a repo branch name. When a Trigger executes the Pipeline in response to a Git push event, you want the Trigger to pass in the branch name to each Workflow's Environment and Service Infrastructure.

First, you could create an Environment and Service Infrastructure using the branch name for the Environment and the branch name plus a suffix -catalog for the Service Infrastructure:

In a Workflow, you can add variables named Environment and ServiceInfra:

In the settings for the Workflow, you can use these variables for Environment and Service Infrastructure using the template button:

You can clone this Workflow to make additional Workflows for your Pipeline, and then change each workflow as needed, leaving the entity variables for Environment and Service Infrastructure the same.

Next, you create a Pipeline and add each Workflow. When you select the Workflow in the Pipeline, the Workflow Variables are required because they are entity settings. You then enter the same variable names you used in the Workflows, ${Environment} and ${ServiceInfra}:

Lastly, you create a Trigger for the Pipeline. When you select the Pipeline in the Trigger, the required Workflow Variables appear. You will only see two variables for all of the Workflows in the Pipeline because they used the same names.

Next, you can enter variables in the Value column for each variable, such as ${ref.split(‘/’)[2]} to use a repo branch name for the Environment variable and ${ref.split(‘/’)[2]}-catalog to use a repo branch name and add the suffix -catalog for ServiceInfra:

Now, when the Trigger is executed, it will pass the variable values to the Environment and Service Infrastructure settings in all Workflows in the Pipeline.


How did we do?