Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md). # 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](workflows-gates.md) 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](workflows-working-runs.md). **Topics** + [How do I unlock an approval gate?](#workflows-approval-conditions) + [When to use the 'Approval' gate](#workflows-approval-when) + [Who can provide an approval?](#workflows-approval-who) + [How do I notify users that an approval is required?](#workflows-approval-notify-methods) + [Can I use an 'Approval' gate to prevent a workflow run from starting?](#workflows-approval-prevent) + [How do workflow approvals work with queued, superseded, and parallel run modes?](#workflows-approval-run-mode) + [Example: An 'Approval' gate](workflows-approval-example.md) + [Adding an 'Approval' gate](workflows-approval-add.md) + [Configuring approval notifications](workflows-approval-notify.md) + [Approving or rejecting a workflow run](workflows-approval-approve.md) + ['Approval' gate YAML](approval-ref.md) ## 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?](#workflows-approval-run-mode). 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](workflows-approval-notify.md). + 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](workflows-approval-approve.md). ## 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?](workflows-gates.md#workflows-gates-prevent). ## 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](workflows-actions.md). We suggest reading the [About queued run mode](workflows-configure-runs.md#workflows-configure-runs-queued), [About superseded run mode](workflows-configure-runs.md#workflows-configure-runs-superseded), [About parallel run mode](workflows-configure-runs.md#workflows-configure-runs-parallel) 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](workflows-configure-runs.md#workflows-configure-runs-queued), 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](#figure-1-workflow-queued-run-mode-ma) illustrates this process. + If you're using the [superseded run mode](workflows-configure-runs.md#workflows-configure-runs-superseded), 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](#figure-2-workflow-superseded-run-mode-ma) illustrates this process. + If you're using the [parallel run mode](workflows-configure-runs.md#workflows-configure-runs-parallel), 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](#figure-3-workflow-parallel-run-mode-ma) illustrates this process. **Figure 1**: 'Queued run mode' and an **Approval** gate ![\[How an 'Approval' gate works with the 'queued run mode'\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/runmode-queued-ma.png) **Figure 2**: 'Superseded run mode' and an **Approval** gate ![\[How an 'Approval' gate works with the 'superseded run mode'\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/runmode-superseded-ma.png) **Figure 3**: 'Parallel run mode' and an **Approval** gate ![\[How an 'Approval' gate works with the 'parallel run mode'\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/runmode-parallel-ma.png) # Example: An 'Approval' gate The following example shows how to add an **Approval** gate called `Approval_01` between two actions called `Staging`, and `Production`. The `Staging` action runs first, the `Approval_01` gate second, and the `Production` action last. The `Production` action only runs if the `Approval_01` gate is unlocked. The `DependsOn` property ensures that the `Staging`, `Approval_01`, and `Production` phases run in sequential order. For more information about the **Approval** gate, see [Requiring approvals on workflow runs](workflows-approval.md). ``` Actions: Staging: # Deploy to a staging server Identifier: aws/ecs-deploy@v1 Configuration: ... Approval_01: Identifier: aws/approval@v1 DependsOn: - Staging Configuration: ApprovalsRequired: 2 Production: # Deploy to a production server Identifier: aws/ecs-deploy@v1 DependsOn: - Approval_01 Configuration: ... ``` # Adding an 'Approval' gate To configure your workflow to require an approval, you must add the **Approval** gate to the workflow. Use the following instructions to add an **Approval** gate to your workflow. For more information about this gate, see [Requiring approvals on workflow runs](workflows-approval.md). ------ #### [ Visual ] **To add an 'Approval' gate to a workflow (visual editor)** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Choose your project. 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. Choose **Edit**. 1. At the top-left, choose **Gates**. 1. In the **Gates** catalog, in **Approval**, choose the plus sign (**\$1**). 1. Choose **Inputs**, and in the **Depends on** field, do the following. Specify an action, action group, or gate that must run successfully in order for this gate to run. By default, when you add a gate to a workflow, the gate is set to depend on the last action in your workflow. If you remove this property, the gate will not depend on anything, and will run first, before other actions. **Note** A gate must be configured to run before or after an action, action group, or gate. It cannot be set up to run in parallel with other actions, action groups, and gates. For more information about the **Depends on** functionality, see [Sequencing gates and actions](workflows-gates-depends-on.md). 1. Choose the **Configuration** tab. 1. In the **Gate name** field, do the following. Specify the name you want to give the gate. All gate names must be unique within the workflow. Gate names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in gate names. 1. (Optional) In the **Number of approvals** field, do the following. Specify the minimum number of approvals required to unlock the **Approval** gate. The minimum is `1`. The maximum is `2`. If omitted, the default is `1`. **Note** If you want to omit the `ApprovalsRequired` property, remove the gate's `Configuration` section from the workflow definition file. 1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing. 1. Choose **Commit**, enter a commit message, and choose **Commit** again. ------ #### [ YAML ] **To add an 'Approval' gate to a workflow (YAML editor)** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Choose your project. 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. Choose **Edit**. 1. Choose **YAML**. 1. Add an `Approval` section and underlying properties using the following example as a guide. For more information, see the ['Approval' gate YAML](approval-ref.md) in the [Workflow YAML definition](workflow-reference.md). ``` Actions: MyApproval_01: Identifier: aws/approval@v1 DependsOn: - PreviousAction Configuration: ApprovalsRequired: 2 ``` For another example, see [Example: An 'Approval' gate](workflows-approval-example.md). 1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing. 1. Choose **Commit**, enter a commit message, and choose **Commit** again. ------ # Configuring approval notifications You can have CodeCatalyst send a notification to a Slack channel informing users that a workflow run requires an approval. Users see the notification and click the link inside of it. The link takes them to a CodeCatalyst approvals page where they can either approve or reject the workflow. You can also configure notifications to inform users that a workflow was approved, rejected, or that the approval request has expired. Use the following instructions to set up Slack notifications. **Before you begin** Make sure you have added an **Approval** gate to your workflow. For more information, see [Adding an 'Approval' gate](workflows-approval-add.md). **To send workflow approval notifications to a Slack channel** 1. Configure CodeCatalyst with Slack. For more information, see [Getting started with Slack notifications](getting-started-notifications.md). 1. In the CodeCatalyst project that contains the workflow that requires an approval, enable notifications, if they're not already enabled. To enable notifications: 1. Navigate to your project and in the navigation pane, choose **Project settings**. 1. At the top, choose **Notifications**. 1. In **Notification events**, choose **Edit notifications**. 1. Turn on **Workflow approval pending** and choose a Slack channel where CodeCatalyst will send the notification. 1. (Optional) Turn on additional notifications to alert people about approved, rejected, and expired approvals. You can turn on **Workflow run approved**, **Workflow run rejected**, **Workflow approval superseded**, and **Workflow approval timed out**. Next to each notification, choose the Slack channel where CodeCatalyst will send the notification. 1. Choose **Save**. # Approving or rejecting a workflow run Workflow runs that include the **Approval** gate will need to be approved or rejected. Users can provide their approval or rejection starting from: + the CodeCatalyst console + a link provided by a team member + an automated Slack notification After a user provides their approval or rejection, this decision cannot be undone. **Note** Only certain users can approve or reject a workflow run. For more information, see [Who can provide an approval?](workflows-approval.md#workflows-approval-who). **Before you begin** Make sure you have added an **Approval** gate to your workflow. For more information, see [Adding an 'Approval' gate](workflows-approval-add.md). **To approve or reject a workflow run starting from the CodeCatalyst console** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Choose your project. 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. In the workflow diagram, choose the box representing the **Approval** gate. A side panel appears. **Note** At this point, you can send the URL of this page to other approvers if you want. 1. Under **Review decision**, choose **Approve** or **Reject**. 1. (Optional) In **Comment - optional**, enter a comment indicating why you approved or rejected the workflow run. 1. Choose **Submit**. **To approve or reject a workflow run starting from a link provided by a team member** 1. Choose the link sent to you by your team member. (You can have your team member read the preceding procedure to obtain the link.) 1. Sign in to CodeCatalyst, if asked. You are redirected to the workflow run approval page. 1. Under **Review decision**, choose **Approve** or **Reject**. 1. (Optional) In **Comment - optional**, enter a comment indicating why you approved or rejected the workflow run. 1. Choose **Submit**. **To approve or reject a workflow run starting from an automated Slack notification** 1. Make sure Slack notifications are set up. See [Configuring approval notifications](workflows-approval-notify.md). 1. In Slack, in the channel to which the approval notification was sent, choose the link in the approval notification. 1. Sign in to CodeCatalyst, if asked. You are redirected to the workflow run page. 1. In the workflow diagram, choose the approval gate. 1. Under **Review decision**, choose **Approve** or **Reject**. 1. (Optional) In **Comment - optional**, enter a comment indicating why you approved or rejected the workflow run. 1. Choose **Submit**. # 'Approval' gate YAML The following is the YAML definition of the **Approval** gate. To learn how to use this gate, see [Requiring approvals on workflow runs](workflows-approval.md). This action definition exists as a section within a broader workflow definition file. For more information about this file, see [Workflow YAML definition](workflow-reference.md). **Note** Most of the YAML properties that follow have corresponding UI elements in the visual editor. To look up a UI element, use **Ctrl\$1F**. The element will be listed with its associated YAML property. ``` # The workflow definition starts here. # See Top-level properties for details. Name: MyWorkflow SchemaVersion: 1.0 Actions: # The 'Approval' gate definition starts here. Approval: Identifier: aws/approval@v1 DependsOn: - another-action Configuration: ApprovalsRequired: number ``` ## Approval (Required) Specify the name you want to give the gate. All gate names must be unique within the workflow. Gate names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in gate names. Default: `Approval_nn`. Corresponding UI: Configuration tab/**Gate name** ## Identifier (*Approval*/**Identifier**) (Required) Identifies the gate. The **Approval** gate supports version `1.0.0`. Do not change this property unless you want to shorten the version. For more information, see [Specifying the action version to use](workflows-action-versions.md). Default: `aws/approval@v1`. Corresponding UI: Workflow diagram/Approval\$1nn/**aws/approval@v1** label ## DependsOn (*Approval*/**DependsOn**) (Optional) Specify an action, action group, or gate that must run successfully in order for this gate to run. By default, when you add a gate to a workflow, the gate is set to depend on the last action in your workflow. If you remove this property, the gate will not depend on anything, and will run first, before other actions. **Note** A gate must be configured to run before or after an action, action group, or gate. It cannot be set up to run in parallel with other actions, action groups, and gates. For more information about the **Depends on** functionality, see [Sequencing gates and actions](workflows-gates-depends-on.md). Corresponding UI: Inputs tab/**Depends on** ## Configuration (*Approval*/**Configuration**) (Optional) A section where you can define the configuration properties of the gate. Corresponding UI: **Configuration** tab ## ApprovalsRequired (*Approval*/Configuration/**ApprovalsRequired**) (Optional) Specify the minimum number of approvals required to unlock the **Approval** gate. The minimum is `1`. The maximum is `2`. If omitted, the default is `1`. **Note** If you want to omit the `ApprovalsRequired` property, remove the gate's `Configuration` section from the workflow definition file. Corresponding UI: Configuration tab/**Number of approvals**