Approval Gates

Overview

Approval Gates enables you to insert a manual approval process for a step in your pipeline. When enabled, the step (and the pipeline run) goes into Pending Approval status when upstream steps finish and the run execution reaches that step. The following can be defined as part of this approval process:

List of approvers: List of users who can approve or reject the step.
List of notifications: Notifications that are sent when the step goes into Pending Approval status.
Timeout: The maximum time the step can stay in Pending Approval status.

Page contents

Configuring Approval Gates Step

To enable Approval Gates, add a new section to your step configuration named requiresApproval.

By default, Approval Gates is disabled. To enable it, add the requiresApproval section to your step configuration.

Using The Defaults

To enable Approval Gates and use the default values for a step, add the requiresApproval flag to your step configuration and set it as true.

In this case, the following defaults are applied to the Pending Approval step:

approvers: Any user with execute permissions can approve or reject a Pending Approval step.
notifications: No notifications are sent.
timeoutSeconds: Defaults to 86400 seconds (24 hours), after which the step is canceled automatically.

Example

Approval Gates Configuration with Default Values

pipelines:
  - name: MyApprovalGatesPipeline
    steps:
      - name: approvalGatesStep
        type: Bash
        configuration:
          requiresApproval: true
        execution:
          onExecute:
            - echo "executing step..."

Customizing Your Configuration

Alternatively, you can define your own requiresApproval configuration section and define the following:

approvers: A list of Artifactory user names that can approve or reject the step.
notifications: A list of SMTP and Slack integrations. Based on the configuration, SMTP and Slack notifications are sent when the step goes into Pending Approval status.
- The listed name for the notifications integration should be an existing SMTP Credentials Integration or Slack Integration.
- The SMTP Credentials Integration requires a list of e-mail recipients to which an approval request will be sent.
- A Slack Integration does not require a list of recipients, since the webhook URL defined in the integration already points to a Slack user or channel to which the notification will be sent.
timeoutSeconds: A window of time, in seconds, in which the approvers can approve or reject the step. If no response is recorded during this timeout period, the step is canceled automatically.

You do not have to include all 3 sections when customizing a step's requiresApproval configuration section. If you do not include one of the sections, this section defaults to the behavior defined above. For example, if you do not provide a configuration for requiresApproval.timeoutSeconds, it defaults to 86400 seconds (24 hours).

The first user that responds from the approvers' list determines if the step is approved or rejected.
Pipelines Admins can approve or reject the step without being listed on the approvers' list.
Artifactory transient users are currently not supported as approvers.

Example

Approval Gates Configuration with Custom Values

pipelines:
  - name: MyApprovalGatesPipeline
    steps:
      - name: approvalGatesStep
        type: Bash
        configuration:
          requiresApproval:
            timeoutSeconds: 43200 # if not approved in this timeframe, the step will be cancelled
            approvers:
              - user1 # must be a valid Artifactory user
              - user2 # must be a valid Artifactory user
            notifications:
              - integrationName: SMTP_Integration # requires SMTP integration
                recipients:
                  - email@example.com
              - integrationName: Slack_Integration # required Slack integration
        execution:
          onExecute:
            - echo "executing step..."

Approving/Rejecting Steps

This section provides information about approving or rejecting a step using the new UI. If you want the perform the same steps using the old UI, see the section below.

After a step moves to Pending Approval state, the approvers can approve or reject the step using the user interface.

To approve or reject a step:

Go to Applications | My Pipelines and run the relevant pipeline.
This displays Pipeline Run page
Click the Approval step (called approvalGatesStep in the example yaml above). This step will be in Pending status.
Click the Approve/Reject button to reveal the following options:
- Approve/Reject button: Click to approve or reject the step.
- Comments field: This optional field enables you to add a meaningful comment for approving or rejecting the step. This has a 100 characters limit.
- Approvers list: This lists the first letter of Artifactory usernames for users who were listed as approvers in the pipelines yaml. Hovering over a letter shows the full Artifactory username.

Approving the step moves it from Pending Approval status to Waiting status. The step then gets picked up for execution by the next available execution node.

Rejecting the step moves it from Pending Approval status to Cancelling status, and eventually the step moves to Cancelled status.

Examples

Live Example

Click here to see this example is action.

This example uses a values.yml file to store the pipeline definitions.
The YAML for this example is available in this repository in the JFrog GitHub account.

template: true   # required for local templates
valuesFilePath: ./values.yml

resources:
  - name: myFirstRepo
    type: GitRepo
    configuration:
      # SCM integration where the repository is located
      gitProvider: {{ .Values.myRepo.gitProvider }} # this will be replaced from values.yml
      # Repository path, including org name/repo name
      path: {{ .Values.myRepo.path }} # this will be replaced from values.yml
      branches:
        # Specifies which branches will trigger dependent steps
        include: master

  - name: myPropertyBag
    type: PropertyBag
    configuration:
      commitSha: 1
      runID: 1

pipelines:
  - name: Approval_Gates_Pipeline
    configuration:
      environmentVariables:
        readOnly:
          pipe_env1: value1
          pipe_env2:
            default: value1
            description: Optional description added in the yaml
            values:
              - value1
              - value2
              - value3  
    steps:
      - name: p1_s1
        type: Bash
        configuration:
          environmentVariables:
            step_env1:
              default: value1
              description: step env1 description
              values:
                - value1
                - value2
                - value3
              allowCustom: true
            step_env2: value2  
            step_env3:
              default: value1            
              description: this is step env3 description
              allowCustom: false              
          #inputResources:
            # Sets up step to be triggered when there are commit events to myFirstRepo
            #- name: myFirstRepo1
        execution:
          onExecute:
            # Data from input resources is available as env variables in the step
            - echo $res_myFirstRepo2_commitSha
            # The next two commands add variables to run state, which is available to all downstream steps in this run
            # Run state documentation: https://www.jfrog.com/confluence/display/JFROG/Creating+Stateful+Pipelines#CreatingStatefulPipelines-RunState
            - add_run_variables current_runid=$run_id
            - add_run_variables commitSha=$res_myFirstRepo2_commitSha
            # This variable is written to pipeline state in p1_s3.
            # So this will be empty during first run and will be set to prior run number in subsequent runs
            # Pipeline state documentation: https://www.jfrog.com/confluence/display/JFROG/Creating+Stateful+Pipelines#CreatingStatefulPipelines-PipelineState
            - echo "Previous run ID is $prev_runid"

      - name: p1_s2
        type: Bash
        configuration:       
          inputSteps:
            - name: p1_s1
        execution:
          onExecute:
            # Demonstrates the availability of an env variable written to run state during p1_s1
            - echo $current_runid


#pipelines:
  #- name: MyApprovalGatesPipeline
    #steps:
      - name: approvalGatesStep
        type: Bash
        configuration:
          inputSteps:
            - name: p1_s2        
          requiresApproval:
            timeoutSeconds: 43200
            approvers:
              - rajeshg
            notifications:
              - integrationName: mySMTP #requires SMTP integration
                recipients:
                  - email@example.com
              - integrationName: mySlack #required Slack integration
        execution:
          onExecute:
            - echo "executing step..."

Approving/Rejecting Steps - Using Old UI