Requiring approvals on workflow runs

You can configure a workflow run to require an approval before it can proceed. To accomplish this, you must add a Approval gate to the workflow. An Approval gate prevents a workflow from proceeding until a user or set of users submit one or more approvals in the CodeCatalyst console. Once all approvals are given, the gate is 'unlocked' and the workflow run is allowed to resume.

Use an Approval gate in your workflow to give your development, operations, and leadership teams a chance to review your changes before they are deployed to a wider audience.

For more information about workflow runs, see Running a workflow.

Topics

• How do I unlock an approval gate?
• When to use the 'Approval' gate
• Who can provide an approval?
• How do I notify users that an approval is required?
• Can I use an 'Approval' gate to prevent a workflow run from starting?
• How do workflow approvals work with queued, superseded, and parallel run modes?
• Example: An 'Approval' gate
• Adding an 'Approval' gate
• Configuring approval notifications
• Approving or rejecting a workflow run
• 'Approval' gate YAML

How do I unlock an approval gate?

To unlock an Approval gate, all of the following conditions must be met:

• Condition 1: The required number of approvals must be submitted. The required number of approvals is configurable, and each user is allowed to submit a single approval.

• Condition 2: All approvals must be submitted before the gate times out. The gate times out 14 days after it is activated. This period is not configurable.

• Condition 3: No one must reject the workflow run. A single rejection will cause the workflow run to fail.

• Condition 4: (Only applies if you are using the superseded run mode.) The run must not be superseded by a later run. For more information, see How do workflow approvals work with queued, superseded, and parallel run modes?.

If any of the conditions are not met, CodeCatalyst stops the workflow and sets the run status to Failed (in the case of Conditions 1 to 3) or Superseded (in the case of Condition 4).

When to use the 'Approval' gate

Typically, you would use an Approval gate in a workflow that deploys applications and other resources to a production server or any environment where quality standards must be validated. By placing the gate before the deployment to production, you give reviewers a chance to validate your new software revision before it becomes available to the public.

Who can provide an approval?

Any user who is a member of your project and who has the Contributor or Project administrator role can provide an approval. Users with the Space administrator role who belong to your project's space can also provide an approval.

Note

Users with the Reviewer role cannot provide approvals.

How do I notify users that an approval is required?

To notify users that an approval is required, you must:

• Have CodeCatalyst send them a Slack notification. For more information, see Configuring approval notifications.

• Go to the page in the CodeCatalyst console where the Approve and Reject buttons are, and paste that page's URL into an email or messaging application addressed to the approvers. For more information about how to navigate to this page, see Approving or rejecting a workflow run.

Can I use an 'Approval' gate to prevent a workflow run from starting?

Yes, with qualifications. For more information, see Can I use a gate to prevent a workflow run from starting?.

How do workflow approvals work with queued, superseded, and parallel run modes?

When using the queued, superseded, or parallel run mode, the Approval gate works in a similar way to actions. We suggest reading the About queued run mode, About superseded run mode, About parallel run mode sections to familiarize yourself with these run modes. Once you have a basic understanding of them, return to this section to find out how these run modes work when the Approval gate is present.

When the Approval gate is present, runs are processed as follows:

• If you're using the queued run mode, runs will queue up behind the run that is currently waiting for approval at the gate. When that gate becomes unlocked (that is, all approvals have been given), the next run in the queue advances to the gate, and waits for approvals. This process continues with queued runs being processed through the gate one-by-one. Figure 1 illustrates this process.

• If you're using the superseded run mode, the behavior is the same as for the queued run mode, except that instead of having runs pile up in the queue at the gate, newer runs supersede (take over from) earlier runs. There are no queues, and any run that is currently waiting at the gate for an approval will be cancelled and superseded by a newer run. Figure 2 illustrates this process.

• If you're using the parallel run mode, runs start in parallel and no queues form. Each run gets processed by the gate immediately since there are no runs in front of it. Figure 3 illustrates this process.

Figure 1: 'Queued run mode' and an Approval gate

Figure 2: 'Superseded run mode' and an Approval gate

Figure 3: 'Parallel run mode' and an Approval gate