Approvals

Updated 2 weeks ago by Michael Katz

Your Workflows and Pipelines can include Approval steps, which require deployments to receive approval before they can proceed. This topic covers:

See Also

Intended Audience

  • DevOps

Jira-based Approvals

For details on Jira integration with Harness, see Jira Integration.

You can add approval steps in both Workflows and Pipelines, and use Jira issue workflow statuses for approval and rejection criteria.

Here is an example of the Workflow statuses for a Jira issue:

Here is a Workflow Jira approval step using the same Jira statuses for criteria:

You can add a Jira approval step in a Pipeline. Here is a Pipeline containing two Workflows and a Jira Approval step.

The first Workflow includes a Jira step that creates a new Jira issue, as described in Jira Integration:

The Variable Name is Jiravar and the Scope is Pipeline. This will enable the output variable to be used in any stage of the Pipeline. The output variable uses the issueId property and so the resulting variable reference is ${Jiravar.issueId}. You can reference the Jira issue anywhere in the Pipeline using ${Jiravar.issueId}.

Next, let's add a Pipeline Approval step that uses ${Jiravar.issueId}.

In a Pipeline, click the Insert a Stage (+) button to add the Approval step:

The new stage dialog appears. Click Approval Step to see the approval settings.

The Approval Step has the following fields:

  • Ticketing System - For Jira, select Jira.
  • Jira Connector - Select the Jira account you want to use by selecting the Collaboration Provider you added for the account, as described in Add Jira as a Collaboration Provider.
  • Project - Select the Jira project containing the Jira issue you will use for approval.
  • Key/Issue ID - Enter the output variable for a Jira issue created in a Workflow, such as ${Jiravar.issueId}. Although we are demonstrating approval using the ${Jiravar.issueId} variable, you can also simply enter the Jira Key/Issue ID for any Jira issue in the Jira project.
  • Timeout - Enter how long Harness should wait for the approval or rejection before failing the deployment.
  • Approved Status Criteria - The Field Name, Operator, and Value drop-down menus are populated from the Jira project you selected. Define the approval criteria using the Jira status items.
  • Rejected Status Criteria - Define the rejection criteria using the Jira status items.

When you finished, the approval step will look something like this:

When you deploy the Pipeline, the Approval Stage will display a link to the Jira issue selected for the approval:

Click the link in the Approval step to see the Jira issue in Jira's UI.

Select the Approval Criteria. In this example, the status Approved fulfills the Approval Criteria.

Once the Jira issue is approved, the Approval stage is green in Deployments, and the deployment continues:

ServiceNow-based Approvals

For details on ServiceNow integration with Harness, see ServiceNow Integration.

You can add approval steps in Pipelines (and Workflows) that use ServiceNow ticket statuses for approval and rejection criteria.

Here is a Pipeline containing two Workflows with a ServiceNow Approval step in between them.

We will walk through how the ServiceNow ticket is created in the first Workflow, and then how a ServiceNow approval is used in Stage 2.

The first Workflow includes a ServiceNow step that creates a new ServiceNow issue, as described in ServiceNow Integration:

The Variable Name is snow and the Scope is Pipeline. This will enable the output variable to be used in any stage of the Pipeline. The output variable uses the issueId property and so the resulting variable reference is ${snow.issueId}. You can reference the ServiceNow issue anywhere in the Pipeline using ${snow.issueId}.

Next, let's add a Pipeline Approval step that uses ${snow.issueId}.

In a Pipeline, click the Insert a Stage (+) button to add the Approval step:

The new stage dialog appears. Click Approval Step to see the approval settings.

The Approval Step has the following fields:

  • Ticketing System - For ServiceNow, select ServiceNow.
  • ServiceNow Connector - Select the ServiceNow account you want to use by selecting the Collaboration Provider you added for the account, as described in Add ServiceNow as a Collaboration Provider. Use the same provider you used to create the ticket in the Workflow.
  • Ticket Type - Select the ServiceNow ticket type. Use the same type as the ticket you created in the Workflow.
  • Issue Number - Enter the output variable for a ServiceNow issue created in a Workflow, such as ${snow.issueId}. Although we are demonstrating approval using the ${snow.issueId} variable, you can also simply enter the ServiceNow ticket number for any ServiceNow ticket in the account.
  • Timeout - Enter how long Harness should wait for the approval or rejection before failing the deployment.
  • Approved Criteria - The Field NameOperator, and Value drop-down menus are populated from the ServiceNow account you selected. Define the approval criteria using the ServiceNow status items.
  • Rejected/Closed Criteria - Define the rejection criteria using the ServiceNow status items.

When you finished, the approval step will look something like this:

When you deploy the Pipeline, the Approval Stage will display a link to the ServiceNow ticket selected for the approval:

Click the link in the Approval step to see the ServiceNow ticket in ServiceNow.

In ServiceNow, select the Approval criteria you defined. In this example, the status Resolved is the approval criteria.

Once the ServiceNow issue is approved, the Approval stage is green in Deployments, and the deployment continues:

You now have a ServiceNow-based approval in your Pipeline that ensures nothing is deployed without your approval.

Harness UI–based Approvals

You can add approval steps in Pipelines (and Workflows) that rely on the Harness UI's User Groups notifications for approval or rejection.

As with other approval mechanisms: In a Pipeline, click the Insert a Stage (+) button to add the Approval step:

The new stage dialog appears. Click Approval Step to see the approval settings.

The Approval Step has the following fields:

  • Ticketing System - For Harness User Group notifications, select Harness UI.
  • User Groups - Select one or more Harness User Groups to notify for approval requests. (Each selected User Group must have Application: read permission for this Application.)
  • Timeout (hours) - Enter how long Harness should wait for the approval before stopping the Pipeline's deployment.
  • Execute in parallel with previous step - You might want to execute steps in parallel if they are deploying to different hosts, or their success is independent of each other.

Click Advanced Settings to display the dialog's remaining fields:

When you are finished, the approval step will look something like this:

When you deploy the Pipeline, the Approval Stage will notify the selected User Group(s), via their configured notification settings, to approve or reject the deployment:

Once an authorized user provides approval, the Approval stage is green in Deployments, and the deployment continues:

You now have a Harness UI–based approval in your Pipeline that ensures nothing is deployed without an authorized user's approval.

To define and modify variables in your Harness UI–based approvals, see Approving Workflow Steps Using Variables.

Shell Script–based Approvals

You can add approval stages in Pipelines—and approval steps in Workflows—that rely on custom shell scripts. Your scripts can test for conditions that you define, and then approve or reject the deployment's progress accordingly.

Pipeline Shell Script–based Approvals

As with other Pipeline approval mechanisms: Click the Insert a Stage (+) button to add the Approval step:

The new stage dialog appears. Click Approval Step to see the approval settings.

The Approval Step has the following fields:

  • Ticketing System - Select Custom Shell Script.
  • Script - Type into this field to replace the placeholder comments with your script. See Sample Script (Pipeline) below for guidelines.
  • Retry Interval (sec) - Enter how long Harness should wait between attempts to successfully execute the script.
  • Timeout (min) - Enter how long Harness should wait for the approval before stopping the Pipeline's deployment.
  • Execute in parallel with previous Step - You might want to execute steps in parallel if they are deploying to different hosts, or their success is independent of each other.
  • Disable step - Select this check box if you want to retain this step in the Pipeline's logic, but suspend the approval requirement.

When you finished, the approval step will look something like this:

Sample Script (Pipeline)

Here is an example of an approval script. From the placeholder comments, note that:

  • Your script must ultimately export the environment variable HARNESS_APPROVAL_STATUS—yielding a ${HARNESS_APPROVAL_STATUS} value of APPROVED or REJECTED.
  • Harness initializes this environment variable for you. Your script is not responsible for initialization, only export.
  • Your script should be idempotent.
  • Your script should follow bash conventions.
curl "http://www.example.com/" > temp.txt
echo $?
if [ "$?" -eq "0" ]
then
export result=APPROVED;
echo $result;
else
echo "no response available. Will try in next iteration";
fi

export HARNESS_APPROVAL_STATUS=$result;

When you deploy the Pipeline, the Approval Stage will attempt to execute your script:

Once the script executes successfully and exports a ${HARNESS_APPROVAL_STATUS} value of APPROVED, the Approval stage is green in Deployments, and the deployment continues:

You now have a script-based approval in your Pipeline that ensures that nothing is deployed without meeting the script's conditions.

Workflow Shell Script–based Approvals

You can add approval steps in Workflows that rely on custom shell scripts. Your scripts can test for conditions that you define, and then approve or reject the deployment's progress accordingly.

As for all approval mechanisms, click Add Step in your Workflow to insert the Approval step:

From the resulting Add Command dialog, select Approval:

This opens the Approval dialog with default settings:

This dialog displays different fields, depending on your selection in the Ticketing System drop-down. For this example, set Ticketing System to Custom Shell Script:

This form of the dialog displays the following fields:

  • Ticketing System – Here, we've selected Custom Shell Script.
  • Script – Type into this field to replace the placeholder comments with your script. See Sample Script (Workflow) below for guidelines.
  • Retry Interval (sec) – Enter how long Harness should wait between attempts to successfully execute the script.
  • Timeout (min) – Enter how long Harness should wait for the approval before stopping the Pipeline's deployment.

Using the sample script below, your completed dialog would look something like this before you click SUBMIT:

Sample Script (Workflow)

Here is an example of an approval script. From the placeholder comments, note that:

  • Your script must ultimately export the environment variable HARNESS_APPROVAL_STATUS—yielding a ${HARNESS_APPROVAL_STATUS} value of APPROVED or REJECTED.
  • Harness initializes this environment variable for you. Your script is not responsible for initialization, only export.
  • Your script should be idempotent.
  • Your script should follow bash conventions.
curl "http://www.example.com/" > temp.txt
echo $?
if [ "$?" -eq "0" ]
then
export result=APPROVED;
echo $result;
else
echo "no response available. Will try in next iteration";
fi

export HARNESS_APPROVAL_STATUS=$result;

When you deploy the Workflow, the Approval step will attempt to execute your script:

Once the script executes successfully and exports a ${HARNESS_APPROVAL_STATUS} value of APPROVED, the Approval step is green in Deployments, and the deployment continues:

Once deployment is complete, the Details panel will display a log of the script's execution:

You now have a script-based approval in your Workflow that ensures that nothing is deployed without meeting the script's conditions.

Approving Workflow Steps Using Variables

In a Workflow Approval step that uses the Harness UI approval mechanism, you can specify predefined or user-defined variables. When the Workflow is deployed, these variables become available as inputs to logging, auditing, and (as shown below) user overrides.

For a list of variables, conventions, and usage details, see Approval Variables. Currently, these variables are available only in Approval steps that set the Ticketing System to Harness UI.

In a given Approval step, you set a shared scope for all the variables you specify: current Phase, whole Workflow, or Pipelines that execute this Workflow.

Specify Approval Variables

To specify Workflow input variables:

  1. Add a Workflow.
  2. To insert an Approval step at a desired location within the Workflow, click Add Command.
  3. In the resulting Add Command modal, select an Approval command.
  4. In the resulting Approval dialog, set the Ticketing System to Harness UI. (This is the only mechanism that currently supports Workflow variables.) Select the User Groups whose members will be able to approve this Workflow step.
  5. Click to open Advanced Settings, then select Publish output in the context. This further expands the dialog.

  1. In Publish Variable Name, enter a parent name for the collection of subordinate variables you will specify below. This parent name helps to avoid conflicts when there are subordinate variables of the same name within the same scope.

  1. Set the Scope for the variables you will specify below. The scopes available are (from narrowest to broadest): Phase, Workflow, or Pipeline.
  2. Click Add Variable to expand the dialog's Additional Input Variables section.
  1. To define a new variable, enter a Name and (optionally) a Default Value. You will use this name—combined with its parent variable name—to reference the variable elsewhere.
  2. To add more input variables, click Add Variable.
    In this example, the parent name is se to approvalStateVars, the Scope is set to Workflow, and we've defined two new variables.

    So, elsewhere within the same Workflow, you would reference these user-defined input variables as (respectively) approvalStateVars.variables.approving_manager and approvalStateVars.variables.swap_route. Neither variable has a Default Value defined.

    When you are done, the dialog will look something like this:
  3. Click Submit to save this Approval step, along with its variables.

Now you can use these variables within the scope you've defined for them, as outlined below.

Approve Workflow Steps Using Variables

Let's see how the Workflow uses the Approval variables defined above when it deploys. Deployment pauses at the Approval step we inserted:

A user (in one of the User Groups configured as approvers) can click that Approval step, to open the Needs Approval settings:

These settings include fields for the user-defined approving_manager and swap_route Additional Input Variables we configured above, as well as a default Comments field. You can enter values for the variables, along with free-text comments, and then click Approve:

Once this step is approved, the Workflow can continue deployment. Note that the values entered above for all three fields appear in this step's Details panel at right:

Note also that the Workflow's final step executes a Shell Script, which echoes the Approval variables. Here's how this script is configured in the Workflow:

Let's take a closer look at the script's text:

echo "This workflow is approved by ${approvalStateVars.variables.approving_manager}"
echo "Swap routes? ${approvalStateVars.variables.swap_route}"
echo "Approved by: ${approvalStateVars.approvedBy.name}"

This script first echoes the two Additional Input Variables. It prepends their parent names, along with the .variables. substring required for user-defined variables, to refer to them as (respectively): approvalStateVars.variables.approving_manager and approvalStateVars.variables.swap_route.

Finally, the script echoes Harness' predefined Approval Variable for the approver's username. It prepends the parent name, to refer to this as approvalStateVars.approvedBy.name.

Predefined Approval variables do not require the .variables. substring.

Click Shell Script to see this script's output in the Details panel, echoing all variables and their values:

Approving Pipeline Stages Using Variables

In an Approval stage within a Pipeline, you can define arbitrary variables. These variables serve as inputs to later stages of the same Pipeline, where they support conditional execution or user overrides.

These Pipeline-level variables work much like the Workflow-level variables described above. However, there are fewer and simpler options: All variables at this level are user-defined, and their scope is always the current Pipeline.

To define Pipeline input variables:

  1. Create a Pipeline.
  2. Add a Pipeline stage.
  3. In the resulting dialog, define this as an Approval stage, and then click Advanced Settings to expand the dialog.
  4. In the newly opened Additional Input Variables section, click Add Variable.

  1. Give your new variable a Name and (optionally) a Default Value. You will later use the name to reference the variable in one or more Execution stages of the Pipeline. You can use the value in an expression to determine whether the Execution stage should execute.
  2. In Publish Variable Name, enter a parent name for the adjacent Additional Input Variables. The parent name helps to avoid conflicts when referencing variables of the same name within the same Pipeline.

    In this example, the parent name is set to releaseInfo, and the input variable's name is releaseTarget. So, in later Pipeline stages, you will reference this variable as releaseInfo.releaseTarget. Its default value is set as PROD.
  3. To add more input variables, click Add Variable. (All variables that you define in this stage will share the same parent name, prepended from the Publish Variable Name field.)
  4. Click Submit to save this stage, along with its variables.

Now you can use these variables in assertion expressions within Pipelines' later Execution stages. For an end-to-end example of defining and accessing input variables, see Skip Based on Assertion Expression.


How did we do?