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). # Running a workflow A *run* is a single iteration of a workflow. During a run, CodeCatalyst performs the actions defined in the workflow configuration file and outputs the associated logs, artifacts, and variables. You can start a run manually, or you can start one automatically, through a *workflow trigger*. An example of a workflow trigger might be a software developer pushing a commit to your main branch. You can also manually stop a workflow run midway through its processing if you started it by mistake. If multiple workflow runs are started at around the same time, you can configure how you want these runs to be queued. You can use the default queuing behavior, where runs are queued one after the other in the order in which they were started, or you can have a later run supersede (or 'take over') from an earlier one to speed up your run throughout. Setting up your workflow runs to occur in parallel, so that no run waits for any other, is also possible. After you've started a workflow run, either manually or automatically, you can view the status of the run and other details. For example, you can see when it was started, who it was started by, and whether it's still running. **Topics** + [Starting a workflow run manually](workflows-manually-start.md) + [Starting a workflow run automatically using triggers](workflows-add-trigger.md) + [Configuring manual-only triggers](workflows-manual-only.md) + [Stopping a workflow run](workflows-stop.md) + [Gating a workflow run](workflows-gates.md) + [Requiring approvals on workflow runs](workflows-approval.md) + [Configuring the queuing behavior of runs](workflows-configure-runs.md) + [Caching files between workflow runs](workflows-caching.md) + [Viewing workflow run status and details](workflows-view-run.md) # Starting a workflow run manually In Amazon CodeCatalyst, you can start a workflow run manually from the CodeCatalyst console. For more information about workflow runs, see [Running a workflow](workflows-working-runs.md). **Note** You can also start a workflow run automatically by [configuring a trigger](workflows-add-trigger.md). **To start a workflow run manually** 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 **Run**. # Starting a workflow run automatically using triggers You can start an Amazon CodeCatalyst workflow run automatically with a workflow trigger. A *workflow trigger*, or simply a *trigger*, allows you to start a workflow run automatically when certain events occur, like a code push. You might want to configure triggers to free your software developers from having to start workflow runs manually through the CodeCatalyst console. You can use three types of trigger: + **Push** – A code push trigger causes a workflow run to start whenever a commit is pushed. + **Pull request** – A pull request trigger causes a workflow run to start whenever a pull request is either created, revised, or closed. + **Schedule** – A schedule trigger causes a workflow run to start on a schedule that you define. Consider using a schedule trigger to run nightly builds of your software so that the latest build is ready for your software developers to work on the next morning. You can use push, pull request, and schedule triggers alone or in combination in the same workflow. Triggers are optional—if you don't configure any, you can only start a workflow manually. **Tip** To see a trigger in action, launch a project with a blueprint. Most blueprints contain a workflow with a trigger. Look for the `Trigger` property in the blueprint's workflow definition file. For more information about blueprints, see [Creating a project with a blueprint](projects-create.md#projects-create-console-template). **Topics** + [Examples: Triggers in workflows](workflows-add-trigger-examples.md) + [Usage guidelines for triggers and branches](workflows-add-trigger-considerations.md) + [Adding triggers to workflows](workflows-add-trigger-add.md) # Examples: Triggers in workflows The following examples show how to add different types of triggers in an Amazon CodeCatalyst workflow definition file. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md). **Topics** + [Example: A simple code push trigger](#workflows-add-trigger-examples-push-simple) + [Example: A simple 'push to main' trigger](#workflows-add-trigger-examples-push-main) + [Example: A simple pull request trigger](#workflows-add-trigger-examples-pull-simple) + [Example: A simple schedule trigger](#workflows-add-trigger-examples-schedule-simple) + [Example: A trigger with a schedule and branches](#workflows-add-trigger-examples-schedule-branches) + [Example: A trigger with a schedule, a push, and branches](#workflows-add-trigger-examples-schedule-push-branches) + [Example: A trigger with a pull and branches](#workflows-add-trigger-examples-pull-branches) + [Example: A trigger with a pull, branches, and a 'CLOSED' event](#workflows-add-trigger-examples-push-pull-close) + [Example: A trigger with a push, branches, and files](#workflows-add-trigger-examples-push-multi) + [Example: A manual trigger](#workflows-add-trigger-examples-manual) + [Example: Triggers in a CI/CD multi-workflow setup](#workflows-add-trigger-usecases) ## Example: A simple code push trigger The following example shows a trigger that starts a workflow run whenever code is pushed to *any* branch in your source repository. When this trigger is activated, CodeCatalyst starts a workflow run using the files in the branch that you're pushing *to* (that is, the destination branch). For example, if you push a commit to `main`, CodeCatalyst starts a workflow run using the workfow definition file and other source files on `main`. As another example, if you push a commit to `feature-branch-123`, CodeCatalyst starts a workflow run using the workfow definition file and other source files on `feature-branch-123`. ``` Triggers: - Type: PUSH ``` **Note** If you want a workflow run to start only when you push to `main`, see [Example: A simple 'push to main' trigger](#workflows-add-trigger-examples-push-main). ## Example: A simple 'push to main' trigger The following example shows a trigger that starts a workflow run whenever code is pushed to the `main` branch—and *only* the `main` branch—in your source repository. ``` Triggers: - Type: PUSH Branches: - main ``` ## Example: A simple pull request trigger The following example shows a trigger that starts a workflow run whenever a pull request is created or revised in your source repository. When this trigger is activated, CodeCatalyst starts a workflow run using the workflow definition file and other source files in the branch that you're pulling *from* (that is, the source branch). For example, if you create a pull request with a source branch called `feature-123` and a destination branch called `main`, CodeCatalyst starts a workflow run using the workfow definition file and other source files on `feature-123`. ``` Triggers: - Type: PULLREQUEST Events: - OPEN - REVISION ``` ## Example: A simple schedule trigger The following example shows a trigger that starts a workflow run at midnight (UTC\$10) every Monday through Friday. When this trigger is activated, CodeCatalyst starts a single workflow run for each branch in your source repository that contains a workflow definition file with this trigger. For example, if you have three branches in your source repository, `main`, `release-v1`, `feature-123`, and each of these branches contains a workflow definition file with the trigger that follows, CodeCatalyst starts three workflow runs: one using the files in `main`, another using the files in `release-v1`, and another using the files in `feature-123`. ``` Triggers: - Type: SCHEDULE Expression: "0 0 ? * MON-FRI *" ``` For more examples of cron expressions you can use in the `Expression` property, see [Expression](workflow-reference.md#workflow.triggers.expression). ## Example: A trigger with a schedule and branches The following example shows a trigger that starts a workflow run at 6:15 pm (UTC\$10) every day. When this trigger is activated, CodeCatalyst starts a workflow run using the files in the `main` branch, and starts additional runs for each branch that begins with `release-`. For example, if you have branches named `main`, `release-v1`, `bugfix-1`, and `bugfix-2` in your source repository, CodeCatalyst starts two workflow runs: one using the the files in `main`, and another using the files in `release-v1`. It does *not* start workflow runs for the `bugfix-1` and `bugfix-1` branches. ``` Triggers: - Type: SCHEDULE Expression: "15 18 * * ? *" Branches: - main - release\-.* ``` For more examples of cron expressions you can use in the `Expression` property, see [Expression](workflow-reference.md#workflow.triggers.expression). ## Example: A trigger with a schedule, a push, and branches The following example shows a trigger that starts a workflow run at midnight (UTC\$10) every day, and whenever code is pushed to the `main` branch. In this example: + A workflow run starts at midnight every day. The workflow run uses the workflow definition file and other source files in the `main` branch. + A workflow run also starts whenever you push a commit to the `main` branch. The workflow run uses the workflow definition file and other source files in the destination branch (`main`). ``` Triggers: - Type: SCHEDULE Expression: "0 0 * * ? *" Branches: - main - Type: PUSH Branches: - main ``` For more examples of cron expressions you can use in the `Expression` property, see [Expression](workflow-reference.md#workflow.triggers.expression). ## Example: A trigger with a pull and branches The following example shows a trigger that starts a workflow run whenever someone opens or modifies a pull request with a destination branch called `main`. Although the branch specified in the `Triggers` configuration is `main`, the workflow run will use the workflow definition file and other source files in the *source* branch (which is the branch you're pulling *from*). ``` Triggers: - Type: PULLREQUEST Branches: - main Events: - OPEN - REVISION ``` ## Example: A trigger with a pull, branches, and a 'CLOSED' event The following example shows a trigger that starts a workflow run whenever a pull request is closed on a branch that starts with `main`. In this example: + When you close a pull request with a destination branch that starts with `main`, a workflow run starts automatically using the workflow definition file and other source files in the (now closed) source branch. + If you've configured your source repository to delete branches automatically after a pull request is merged, these branches will never have the chance to enter the `CLOSED` state. This means that merged branches will not activate the pull request `CLOSED` trigger. The only way to activate the `CLOSED` trigger in this scenario is to close the pull request without merging it. ``` Triggers: - Type: PULLREQUEST Branches: - main.* Events: - CLOSED ``` ## Example: A trigger with a push, branches, and files The following example shows a trigger that starts a workflow run whenever a change is made to the `filename.txt` file, or any file in the `src` directory, on the `main` branch. When this trigger is activated, CodeCatalyst starts a workflow run using the workflow definition file and other source files in the `main` branch. ``` Triggers: - Type: PUSH Branches: - main FilesChanged: - filename.txt - src\/.* ``` ## Example: A manual trigger To configure a manual trigger, omit the `Triggers` section from the workflow definition file. Without this section, users are forced to start the workflow manually by choosing the **Run** button in the CodeCatalyst console. For more information, see [Starting a workflow run manually](workflows-manually-start.md). ## Example: Triggers in a CI/CD multi-workflow setup This example describes how to set up triggers when you want to use separate Amazon CodeCatalyst workflows for continuous integration (CI) and continuous deployment (CD). In this scenario, you set up two workflows: + a **CI workflow** – this workflow builds and tests your application when a pull request is created or revised. + a **CD workflow** – this workflow builds and deploys your application when a pull request is merged. The **CI workflow**'s definition file would look similar to this: ``` Triggers: - Type: PULLREQUEST Branches: - main Events: - OPEN - REVISION Actions: BuildAction: instructions-for-building-the-app TestAction: instructions-for-test-the-app ``` The `Triggers` code indicates to start a workflow run automatically whenever a software developer creates a pull request (or [modifies one](pull-requests-update.md)) asking to merge their feature branch to the `main` branch. CodeCatalyst starts the workflow run using the source code in the source branch (which is the feature branch). The **CD workflow**'s definition file would look similar to this: ``` Triggers: - Type: PUSH Branches: - main Actions: BuildAction: instructions-for-building-the-app DeployAction: instructions-for-deploying-the-app ``` The `Triggers` code indicates to start the workflow automatically when a merge to `main` occurs. CodeCatalyst starts the workflow run using the source code in the `main` branch. # Usage guidelines for triggers and branches This section describes some of the main guidelines when setting up Amazon CodeCatalyst triggers that include branches. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md). + **Guideline 1:** For both push and pull request triggers, if you are going to specify a branch, you must specify the destination (or 'to') branch in the trigger configuration. Never specify the source (or 'from') branch. In the following example, a push from any branch to `main` activates the workflow. ``` Triggers: - Type: PUSH Branches: - main ``` In the following example, a pull request from any branch into `main` activates the workflow. ``` Triggers: - Type: PULLREQUEST Branches: - main Events: - OPEN - REVISION ``` + **Guideline 2:** For push triggers, after the workflow is activated, the workflow will run using the workflow definition file and source files in the *destination* branch. + **Guideline 3:** For pull request triggers, after the workflow is activated, the workflow will run using the workflow definition file and source files in the *source* branch (even though you specified the destination branch in the trigger configuration). + **Guideline 4:** The exact same trigger in one branch might not run in another branch. Consider the following push trigger: ``` Triggers: - Type: PUSH Branches: - main ``` If the workflow definition file containing this trigger exists in `main` and gets cloned to `test`, the workflow will never start automatically using the files in `test` (although you could start the workflow *manually* to have it use the files in `test`). Review **Guideline 2** to understand why the workflow will never run automatically using the files in `test`. Consider also the following pull request trigger: ``` Triggers: - Type: PULLREQUEST Branches: - main Events: - OPEN - REVISION ``` If the workflow definition file containing this trigger exists in `main`, the workflow will never run using the files in `main`. (However, if you create a `test` branch off of `main`, the workflow will run using the files in `test`.) Review **Guideline 3** to understand why. # Adding triggers to workflows Use the following instructions to add a push, pull, or schedule trigger to your Amazon CodeCatalyst workflow. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md). ------ #### [ Visual ] **To add a trigger (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. Choose **Visual**. 1. In the workflow diagram, choose the **Source** and **Triggers** box. 1. In the configuration pane, Choose **Add trigger**. 1. In the **Add trigger** dialog box, supply information in the fields, as follows. **Trigger type** Specify the type of trigger. You can use one of the following values: + **Push** (visual editor) or `PUSH` (YAML editor) A push trigger starts a workflow run when a change is pushed to your source repository. The workflow run will use the files in the branch that you're pushing *to* (that is, the destination branch). + **Pull request** (visual editor) or `PULLREQUEST` (YAML editor) A pull request trigger starts a workflow run when a pull request is opened, updated, or closed in your source repository. The workflow run will use the files in the branch that you're pulling *from* (that is, the source branch). + **Schedule** (visual editor) or `SCHEDULE` (YAML editor) A schedule trigger starts workflow runs on a schedule defined by a cron expression that you specify. A separate workflow run will start for each branch in your source repository using the branch's files. (To limit the branches that the trigger activates on, use the **Branches** field (visual editor) or `Branches` property (YAML editor).) When configuring a schedule trigger, follow these guidelines: + Only use one schedule trigger per workflow. + If you've defined multiple workflows in your CodeCatalyst space, we recommend that you schedule no more than 10 of them to start concurrently. + Make sure you configure the trigger's cron expression with adequate time between runs. For more information, see [Expression](workflow-reference.md#workflow.triggers.expression). For examples, see [Examples: Triggers in workflows](workflows-add-trigger-examples.md). **Events for pull request** This field only appears if you selected the **Pull request** trigger type. Specify the type of pull request events that will start a workflow run. The following are the valid values: + **Pull request is created** (visual editor) or `OPEN` (YAML editor) The workflow run is started when a pull request is created. + **Pull request is closed** (visual editor) or `CLOSED` (YAML editor) The workflow run is started when a pull request is closed. The `CLOSED` event's behavior is tricky, and is best understood through an example. See [Example: A trigger with a pull, branches, and a 'CLOSED' event](workflows-add-trigger-examples.md#workflows-add-trigger-examples-push-pull-close) for more information. + **New revision is made to pull request** (visual editor) or `REVISION` (YAML editor) The workflow run is started when a revision to a pull request is created. The first revision is created when the pull request is created. After that, a new revision is created every time someone pushes a new commit to the source branch specified in the pull request. If you include the `REVISION` event in your pull request trigger, you can omit the `OPEN` event, since `REVISION` is a superset of `OPEN`. You can specify multiple events in the same pull request trigger. For examples, see [Examples: Triggers in workflows](workflows-add-trigger-examples.md). **Schedule** This field only appears if you selected the **Schedule** trigger type. Specify the cron expression that describes when you want your scheduled workflow runs to occur. Cron expressions in CodeCatalyst use the following six-field syntax, where each field is separated by a space: *minutes* *hours* *days-of-month* *month* *days-of-week* *year* **Examples of cron expressions** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/workflows-add-trigger-add.html) When specifying cron expressions in CodeCatalyst, make sure you follow these guidelines: + Specify a single cron expression per `SCHEDULE` trigger. + Enclose the cron expression in double-quotes (`"`) in the YAML editor. + Specify the time in Coordinated Universal Time (UTC). Other time zones are not supported. + Configure at least 30 minutes between runs. A faster cadence is not supported. + Specify the *days-of-month* or *days-of-week* field, but not both. If you specify a value or an asterisk (`*`) in one of the fields, you must use a question mark (`?`) in the other. The asterisk means 'all' and the question mark means 'any'. For more examples of cron expressions and information about wildcards like `?`, `*`, and `L`, see the [Cron expressions reference](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-cron-expressions.html) in the *Amazon EventBridge User Guide*. Cron expressions in EventBridge and CodeCatalyst work exactly the same way. For examples of schedule triggers, see [Examples: Triggers in workflows](workflows-add-trigger-examples.md). **Branches** and **Branch pattern** (Optional) Specify the branches in your source repository that the trigger monitors in order to know when to start a workflow run. You can use regex patterns to define your branch names. For example, use `main.*` to match all branches beginning with `main`. The branches to specify are different depending on the trigger type: + For a push trigger, specify the branches you're pushing *to*, that is, the *destination* branches. One workflow run will start per matched branch, using the files in the matched branch. Examples: `main.*`, `mainline` + For a pull request trigger, specify the branches you're pushing *to*, that is, the *destination* branches. One workflow run will start per matched branch, using the workflow definition file and source files in the **source** branch (*not* the matched branch). Examples: `main.*`, `mainline`, `v1\-.*` (matches branches that start with `v1-`) + For a schedule trigger, specify the branches that contain the files that you want your scheduled run to use. One workflow run will start per matched branch, using the the workflow definition file and source files in the matched branch. Examples: `main.*`, `version\-1\.0` **Note** If you *don't* specify branches, the trigger monitors all branches in your source repository, and will start a workflow run using the workflow definition file and source files in: The branch you're pushing *to* (for push triggers). For more information, see [Example: A simple code push trigger](workflows-add-trigger-examples.md#workflows-add-trigger-examples-push-simple). The branch you're pulling *from* (for pull request triggers). For more information, see [Example: A simple pull request trigger](workflows-add-trigger-examples.md#workflows-add-trigger-examples-pull-simple). All branches (for schedule triggers). One workflow run will start per branch in your source repository. For more information, see [Example: A simple schedule trigger](workflows-add-trigger-examples.md#workflows-add-trigger-examples-schedule-simple). For more information about branches and triggers, see [Usage guidelines for triggers and branches](workflows-add-trigger-considerations.md). For more examples, see [Examples: Triggers in workflows](workflows-add-trigger-examples.md). **Files changed** This field only appears if you selected the **Push** or **Pull request** trigger type. Specify the files or folders in your source repository that the trigger monitors in order to know when to start a workflow run. You can use regular expressions to match file names or paths. For examples, see [Examples: Triggers in workflows](workflows-add-trigger-examples.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. ------ #### [ YAML ] **To add a trigger (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 a `Triggers` section and underlying properties using the following example as a guide. For more information, see the [Triggers](workflow-reference.md#triggers-reference) in the [Workflow YAML definition](workflow-reference.md). A code push trigger might look like this: ``` Triggers: - Type: PUSH Branches: - main ``` A pull request trigger might look like this: ``` Triggers: - Type: PULLREQUEST Branches: - main.* Events: - OPEN - REVISION - CLOSED ``` A schedule trigger might look like this: ``` Triggers: - Type: SCHEDULE Branches: - main.* # Run the workflow at 1:15 am (UTC+0) every Friday until the end of 2023 Expression: "15 1 ? * FRI 2022-2023" ``` For more examples of cron expressions you can use in the `Expression` property, see [Expression](workflow-reference.md#workflow.triggers.expression). For more examples of push, pull request, and schedule triggers, see [Examples: Triggers in workflows](workflows-add-trigger-examples.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 manual-only triggers You can limit a workflow so that it can only be started manually by your team using the **Run** button in the CodeCatalyst console. To configure this functionality, you must remove the `Triggers` section in the workflow definition file. The `Triggers` section is included by default when you create a workflow, but the section is optional and can be removed. Use the following instructions to remove the `Triggers` section in the workflow definition file so that the workflow can only be started manually. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md). For more information about running workflows, see [Running a workflow](workflows-working-runs.md). ------ #### [ Visual ] **To remove the 'Triggers' section (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. Choose **Visual**. 1. Choose the **Source** box in the workflow diagram. 1. Under **Triggers**, choose the trash can icon to remove the `Triggers` section from the workflow. 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 remove the 'Triggers' section (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. Find the `Triggers` section and remove it. 1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing. 1. Choose **Commit**, enter a commit message, and choose **Commit** again. ------ # Stopping a workflow run Use the following procedure to stop a workflow run that's in progress. You might want to stop a run if it was started by accident. When you stop a workflow run, CodeCatalyst waits for in-progress actions to complete before it marks the run as **Stopped** in the CodeCatalyst console. Any actions that didn't have a chance to start will not be started, and will be marked as **Abandoned**. **Note** If a run is queued (that is, it has no in-progress actions), then the run is stopped immediately. For more information about workflow runs, see [Running a workflow](workflows-working-runs.md). **To stop a workflow run** 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. Under **Workflows**, choose **Runs** and choose the in-progress run from the list. 1. Choose **Stop**. # Gating a workflow run A *gate* is a workflow component that you can use to prevent a workflow run from proceeding unless certain conditions are met. An example of a gate is the **Approval** gate where users must submit an approval in the CodeCatalyst console before the workflow run is allowed to continue. You can add gates between sequences of actions in a workflow, or before the first action (which runs immediately after the **Source** downloads). You can also add gates after the last action, if you have a need to do so. For more information about workflow runs, see [Running a workflow](workflows-working-runs.md). **Topics** + [Gate types](#workflows-gates-types) + [Can I set up a gate to run in parallel to another action?](#workflows-approval-parallel) + [Can I use a gate to prevent a workflow run from starting?](#workflows-gates-prevent) + [Limitations of gates](#workflows-gate-limitations) + [Adding a gate to a workflow](workflows-gates-add.md) + [Sequencing gates and actions](workflows-gates-depends-on.md) + [Specifying the version of a gate](workflows-gates-version.md) ## Gate types Currently, Amazon CodeCatalyst supports one type of gate: the **Approval** gate. For more information, see [Requiring approvals on workflow runs](workflows-approval.md). ## Can I set up a gate to run in parallel to another action? No. Gates can only run before or after an action. For more information, see [Sequencing gates and actions](workflows-gates-depends-on.md). ## Can I use a gate to prevent a workflow run from starting? Yes, with qualifications. You can prevent a workflow run from *performing tasks*, which is slightly different from preventing it from *starting*. To prevent a workflow from performing tasks, add a gate before the very first action in a workflow. In this scenario, a workflow run *will start*—meaning it will download your source repository files—but it will be prevented from performing tasks until the gate is unlocked. **Note** Workflows that start and then get blocked by a gate still count against your *Maximum number of concurrent workflow runs per space* quota and other quotas. To ensure that you do not exceed workflow quotas, consider using a workflow trigger to conditionally start a workflow instead of using a gate. Also consider using a pull request approval rule instead of a gate. For more information about quotas, triggers, and pull request approval rules, see [Quotas for workflows in CodeCatalyst](workflows-quotas.md), [Starting a workflow run automatically using triggers](workflows-add-trigger.md), and [Managing requirements for merging a pull request with approval rules](source-pull-requests-approval-rules.md). ## Limitations of gates Gates have the following limitations: + Gates cannot be used in conjunction with the compute sharing feature. For more information about this feature, see [Sharing compute across actions](compute-sharing.md). + Gates cannot be used within action groups. For more information about action groups, see [Grouping actions into action groups](workflows-group-actions.md). # Adding a gate to a workflow In Amazon CodeCatalyst, you can add a gate to a workflow to prevent it from proceeding unless certain conditions are met. Use the following instructions to add a gate to a workflow. For more information about gates, see [Gating a workflow run](workflows-gates.md). **To add and configure a gate** 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 **Visual**. 1. On the left, choose **Gates**. 1. In the gate catalog, search for a gate, and then choose the plus sign (**\$1**) to add the gate to your workflow. 1. Configure the gate. Choose **Visual** to use the visual editor, or **YAML** to use the YAML editor. For detailed instructions, see: + [Adding an 'Approval' gate](workflows-approval-add.md) 1. (Optional) Choose **Validate** to make sure the YAML code is valid. 1. Choose **Commit** to commit your changes. # Sequencing gates and actions In Amazon CodeCatalyst, you can set up a gate to run before or after a workflow action, action group, or gate. For example, you might set up an `Approval` gate to run before a `Deploy` action. In this case, the `Deploy` action is said to *depend on* the `Approval` gate. To set up dependencies between gates and actions, configure the gate or action's **Depends on** property. For instructions, see [Setting up dependencies between actions](workflows-depends-on-set-up.md). The referenced instructions refer to workflow *actions* but apply equally to gates. For an example of how to set up the **Depends on** property with a gate, see [Example: An 'Approval' gate](workflows-approval-example.md). For more information about gates, see [Gating a workflow run](workflows-gates.md). For more information about workflow actions, see [Configuring workflow actions](workflows-actions.md). # Specifying the version of a gate By default, when you add a gate to a workflow, CodeCatalyst adds the full version to the workflow definition file using the format: `vmajor.minor.patch` For example: ``` My-Gate: Identifier: aws/approval@v1 ``` You can lengthen the version so that the workflow uses a specific major or minor version of the gate. For instructions, see [Specifying the action version to use](workflows-action-versions.md). The referenced topic refers to workflow actions but applies equally to gates. For more information about gates in CodeCatalyst, see [Gating a workflow run](workflows-gates.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** # Configuring the queuing behavior of runs By default in Amazon CodeCatalyst, when multiple workflow runs occur at the same time, CodeCatalyst queues them up, and processes them one by one, in the order that they were started. You can change this default behavior by specifying a *run mode*. There are a few run modes: + (Default) Queued run mode – CodeCatalyst processes runs one by one + Superseded run mode – CodeCatalyst processes runs one by one, with newer runs overtaking older ones + Parallel run mode – CodeCatalyst processes runs in parallel For more information about workflow runs, see [Running a workflow](workflows-working-runs.md). **Topics** + [About queued run mode](#workflows-configure-runs-queued) + [About superseded run mode](#workflows-configure-runs-superseded) + [About parallel run mode](#workflows-configure-runs-parallel) + [Configuring the run mode](#workflows-configure-runs-configure) ## About queued run mode In *queued run mode*, runs occur in series, with waiting runs forming a queue. Queues form at the entry points to actions and action groups, so you can have *multiple queues within the same workflow* (see [Figure 1](#figure-1-workflow-queued-run-mode)). When a queued run enters an action, the action is locked and no other runs can enter. When the run finishes and exits the action, the action becomes unlocked and ready for the next run. [Figure 1](#figure-1-workflow-queued-run-mode) illustrates a workflow configured in queued run mode. It shows: + Seven runs working their way through the workflow. + Two queues: one outside the entry to the input source (**Repo:main**), and one outside the entry to the **BuildTestActionGroup** action. + Two locked blocks: the input source (**Repo:main**) and the **BuildTestActionGroup**. Here's how things will transpire as the workflow runs finish processing: + When **Run-4d444** finishes cloning the source repository, it will exit the input source and join the queue behind **Run-3c333**. Then, **Run-5e555** will enter the input source. + When **Run-1a111** finishes building and testing, it will exit the **BuildTestActionGroup** action and enter the **DeployAction** action. Then, **Run-2b222** will enter the **BuildTestActionGroup** action. **Figure 1**: A workflow configured in 'queued run mode' ![\[A workflow configured in 'queued run mode'\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/RunMode-Queued.png) Use queued run mode if: + **You want to keep a one-to-one relationship between features and runs – these features may be grouped when using superseded mode**. For example, when you merge feature 1 in commit 1, run 1 starts, and when you merge feature 2 in commit 2, run 2 starts, and so on. If you were to use superseded mode instead of queued mode, your features (and commits) will be grouped together in the run that supersedes the others. + **You want to avoid race conditions and unexpected problems that may occur when using parallel mode**. For example, if two software developers, Wang and Saanvi, start workflow runs at roughly the same time to deploy to an Amazon ECS cluster, Wang's run might begin integration tests on the cluster while Saanvi's run deploys new application code to the cluster, causing Wang's tests either to fail or to test the wrong code. As another example, you might have a target that doesn't have a locking mechanism, in which case the two runs could overwrite each other's changes in unexpected ways. + **You want to limit the load** on the compute resources that CodeCatalyst uses to process your runs. For example, if you have three actions in your workflow, you can have a maximum of three runs occurring at the same time. Imposing a limit on the number of runs that can occur at once makes run throughput more predictable. + **You want to constrain the number of requests made to third-party services** by the workflow. For example, your workflow might have a build action that includes instructions to pull an image from Docker Hub. [Docker Hub limits the number of pull requests](https://www.docker.com/increase-rate-limits) you can make to a certain number per hour per account, and you will be locked out if you go over the limit. Using queued run mode to slow down your run throughput will have the effect of generating fewer requests to Docker Hub per hour, thus limiting the potential for lockouts and resulting build and run failures. **Maximum queue size**: 50 Notes on **Maximum queue size**: + The maximum queue size refers to the maximum number of runs allowed across *all queues* in the workflow. + If a queue becomes longer than 50 runs, then CodeCatalyst drops the 51st and subsequent runs. **Failure behavior**: If a run becomes unresponsive while it's being processed by an action, then the runs behind it are held up in the queue until the action times out. Actions time out after an hour. If a run fails inside an action, then the first queued run behind it is allowed to proceed. ## About superseded run mode *Superseded run mode* is the same as *queued run mode* except that: + If a queued run catches up to another run in the queue, the later run supersedes (takes over from) the earlier run, and the earlier run is canceled and marked as 'superseded'. + As an outcome of the behavior described in the first bullet, a queue can only include one run when superseded run mode is used. Using the workflow in [Figure 1](#figure-1-workflow-queued-run-mode) as a guide, applying superseded run mode to this workflow would result in the following: + **Run-7g777** would supersede the other two runs in its queue, and would be the only run remaining in **Queue \$11**. **Run-6f666** and **Run-5e555** would be canceled. + **Run-3c333** would supersede **Run-2b222** and be the only run remaining in **Queue \$12**. **Run-2b222** would be canceled. Use superseded run mode if you want: + better throughput than with queued mode + even fewer requests into third-party services than with queued mode; this is advantageous if the third-party service has rate limits, such as Docker Hub ## About parallel run mode In *parallel run mode*, runs are independent of one another and don’t wait for other runs to complete before starting. There are no queues, and run throughput is limited only by how fast the actions inside the workflow take to complete. Use parallel run mode in development environments where each user has their own feature branch and deploys to targets that are not shared by other users. **Important** If you have a shared target that multiple users can deploy to, such as a Lambda function in a production environment, do not use parallel mode, because race conditions may result. A *race condition* occurs when parallel workflow runs attempt to change a shared resource at the same time, leading to unpredictable results. **Maximum number of parallel runs**: 1000 per CodeCatalyst space ## Configuring the run mode You can set the run mode to queued, superseded, or parallel. The default is queued. When you change the run mode from queued or superseded to parallel, CodeCatalyst cancels the runs that are queued, and allows the runs that are currently being processed by an action to finish before canceling them. When you change the run mode from parallel to queued or superseded, CodeCatalyst lets all currently-running parallel runs complete. Any runs that you start after changing the run mode to queued or superseded use the new mode. ------ #### [ Visual ] **To change the run mode using the 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-right, choose **Workflow properties**. 1. Expand **Advanced**, and under **Run mode**, choose one of the following: 1. **Queued** – see [About queued run mode](#workflows-configure-runs-queued) 1. **Superseded** – see [About superseded run mode](#workflows-configure-runs-superseded) 1. **Parallel** – see [About parallel run mode](#workflows-configure-runs-parallel) 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 change the run mode using the 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 the `RunMode` property, like this: ``` Name: Workflow_6d39 SchemaVersion: "1.0" RunMode: QUEUED|SUPERSEDED|PARALLEL ``` For more information, see the description of the `RunMode` property in the [Top-level properties](workflow-reference.md#workflow.top.level) section of the [Workflow YAML definition](workflow-reference.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. ------ # Caching files between workflow runs When file caching is enabled, the build and test actions save on-disk files to a cache and restore them from that cache in subsequent workflow runs. Caching reduces the latency caused by building or downloading dependencies that haven’t changed between runs. CodeCatalyst also supports fallback caches, which can be used to restore partial caches containing some of the needed dependencies. This helps reduce the latency impacts of a cache miss. **Note** File caching is only available with the Amazon CodeCatalyst [build](build-workflow-actions.md) and [test](test-workflow-actions.md) actions, and only when they are configured to use the **EC2** [compute type](workflows-working-compute.md#compute.types). **Topics** + [About file caching](#workflows-caching.files) + [Creating a cache](#workflows-caching.fallback) + [File caching constraints](#workflows-caching.constraints) ## About file caching File caching allows you to organize your data into multiple caches, which are each referenced under the `FileCaching` property. Each cache saves a directory specified by a given path. The specified directory will be restored in future workflow runs. The following is an example YAML snippet for caching with multiple caches named `cacheKey1` and `cacheKey2`. ``` Actions: BuildMyNpmApp: Identifier: aws/build@v1 Inputs: Sources: - WorkflowSource Configuration: Steps: - Run: npm install - Run: npm run test Caching: FileCaching: cacheKey1: Path: file1.txt RestoreKeys: - restoreKey1 cacheKey2: Path: /root/repository RestoreKeys: - restoreKey2 - restoreKey3 ``` **Note** CodeCatalyst uses multilayered caching, which consists of a local cache and a remote cache. When provisioned fleets or on-demand machines encounter a cache miss on a local cache, dependencies will be restored from a remote cache. As a result, some action runs may experience latency from downloading a remote cache. CodeCatalyst applies cache access restrictions to ensure that an action in one workflow cannot modify the caches from a different workflow. This protects each workflow from others that might push incorrect data that impact builds or deployments. Restrictions are enforced with cache-scopes which isolate caches to every workflow and branch pairing. For example, `workflow-A` in branch `feature-A` has a different file cache than `workflow-A` in sibling branch `feature-B`. Cache misses occur when a workflow looks for a specified file cache and is unable to find it. This can occur for multiple reasons, such as when a new branch is created or when a new cache is referenced and it hasn't been created yet. It can also occur when a cache expires, which by default occurs 14 days after it was last used. To mitigate cache misses and increase the rate of cache hits, CodeCatalyst supports fallback caches. Fallback caches are alternate caches and provide an opportunity to restore partial-caches, which can be an older version of a cache. A cache is restored by first searching for a match under `FileCaching` for the property name, and if not found, evaluates `RestoreKeys`. If there is a cache miss for both the property name and all `RestoreKeys`, the workflow will continue to run, as caching is best effort and not guaranteed. ## Creating a cache You can use the following instructions to add a cache to your workflow. ------ #### [ Visual ] **To add a cache using the 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. Choose **Visual**. 1. In the workflow diagram, choose the action where you want to add your cache. 1. Choose **Configuration**. 1. Under **File caching - optional**, choose **Add cache** and enter information into the fields, as follows: **Key** Specify the name of your primary cache property name. Cache property names must be unique within your workflow. Each action can have up to five entries in `FileCaching`. **Path** Specify the associated path for your cache. **Restore keys - optional** Specify the restore key to use as a fallback when the primary cache property can't be found. Restore key names must be unique within your workflow. Each cache can have up to five entries in `RestoreKeys`. 1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing. 1. Choose **Commit**, enter a commit message, and then choose **Commit** again. ------ #### [ YAML ] **To add a cache using the 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. In a workflow action, add code similar to the following: ``` action-name: Configuration: Steps: ... Caching: FileCaching: key-name: Path: file-path # # Specify any additional fallback caches # RestoreKeys: # - restore-key ``` 1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing. 1. Choose **Commit**, enter a commit message, and choose **Commit** again. ------ ## File caching constraints The following are the constraints for the property name and `RestoreKeys`: + Names must be unique within a workflow. + Names are limited to alphanumeric characters (A-Z, a-z, 0-9), hyphens (-), and underscores (\$1). + Names can have up to 180 characters. + Each action can have up to five caches in `FileCaching`. + Each cache can have up to five entries in `RestoreKeys`. The following are the constraints for paths: + Asterisks (\$1) are not allowed. + Paths can have up to 255 characters. # Viewing workflow run status and details IN Amazon CodeCatalyst, you can view the status and details of a single workflow run, or multiple runs at the same time. For a list of possible run states see [Workflow run states](workflows-view-run-status.md). **Note** You can also view the workflow status, which is different from the workflow *run* status. For more information, see [Viewing a workflow's status](workflows-view-status.md). For more information about workflow runs, see [Running a workflow](workflows-working-runs.md). **Topics** + [Viewing the status and details of a single run](#workflows-view-run-single) + [Viewing the status and details of all runs in your project](#workflows-view-run-all) + [Viewing the status and details of all runs of a specific workflow](#workflows-view-run-wf) + [Viewing runs of a workflow in the workflow diagram](#workflows-view-run-wf-diagram) ## Viewing the status and details of a single run You might want to view the status and details of a single workflow run to check whether it was successful, to see at what time it was completed, or to view who or what started it. **To view the status and details of a single run** 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. Under the workflow's name, choose **Runs**. 1. In **Run history**, in the **Run ID** column, choose a run. For example, `Run-95a4d`. 1. Under the run's name, do one of the following: + **Visual** to see a workflow diagram showing your workflow run's actions and their status (see [Workflow run states](workflows-view-run-status.md)). This view also shows the source repository and branch used during the run. In the workflow diagram, choose an action to see details such as logs, reports, and outputs generated by the action during the run. The information shown depends on which action type is selected. For more information about viewing build or deploy logs, see [Viewing the results of a build action](build-view-results.md) or [Viewing the deployment logs](deploy-deployment-logs.md). + **YAML** to see the workflow definition file that was used for the run. + **Artifacts** to see the artifacts produced by the workflow run. For more information about artifacts, see [Sharing artifacts and files between actions](workflows-working-artifacts.md). + **Reports** to see the test reports and other types of reports produced by the workflow run. For more information about reports, see [Quality report types](test-workflow-actions.md#test-reporting). + **Variables** to see the output variables produced by the workflow run. For more information about variables, see [Using variables in workflows](workflows-working-with-variables.md). **Note** If the run's parent workflow was deleted, a message indicating this fact appears at the top of the run details page. ## Viewing the status and details of all runs in your project You might want to view the status and details of all workflow runs within your project understand how much workflow activity is going on in your project, and learn about the overall health of your workflows. **To view the status and details of all runs in your project** 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. Under **Workflows**, choose **Runs**. All the runs, for all workflows, in all branches, across all repositories in your project, are displayed. The page includes the following columns: + **Run ID** – The unique identifier of the run. Choose the run ID link to view detailed information about the run. + **Status** – The processing status of the workflow run. For more information about run states, see [Workflow run states](workflows-view-run-status.md). + **Trigger** – The person, commit, pull request (PR), or schedule that started the workflow run. For more information, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md). + **Workflow** – The name of the workflow for which a run was started, and the source repository and branch where the workflow definition file resides. You might need to expand the column width to see this information. **Note** If this column is set to **Not available**, it's usually because the associated workflow was deleted or moved. + **Start time** – The time when the workflow run started. + **Duration** – How long the workflow run took to process. Very long or very short durations might indicate problems. + **End time** – The time when the workflow run ended. ## Viewing the status and details of all runs of a specific workflow You might want to view the status and details of all runs associated with a specific workflow to see if any runs are creating bottlenecks within the workflow, or to see which runs are currently in progress or have completed. **To view the status and details of all runs of a specific workflow** 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. Under the workflow's name, choose **Runs**. The runs associated with the chosen workflow appear. The page is divided into two sections: + **Active runs** – Displays runs that are in progress. These runs will be in one of the following states: **In progress**. + **Run history** – Displays runs that have completed (that is, not in progress). For more information about run states, see [Workflow run states](workflows-view-run-status.md). ## Viewing runs of a workflow in the workflow diagram You can view the status of all runs of a workflow as they progress together through the workflow. The runs are displayed within the workflow diagram (as opposed to in a list view). This gives you a visual representation of which runs are being processed by which actions, and which runs are waiting in a queue. **To view the status of multiple runs as they progress together through a workflow** **Note** This procedure only applies if your workflow is using the queued or superseded run mode. For more information, see [Configuring the queuing behavior of runs](workflows-configure-runs.md). 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. **Note** Make sure you're looking at a workflow page and not a run page. 1. Choose the **Latest state** tab on the upper left. A workflow diagram appears. 1. Review the workflow diagram. The diagram shows all the runs that are currently in progress within the workflow, and the latest runs that have finished. More specifically: + Runs that appear at the top, before **Sources**, are queued and waiting to start. + Runs that appear between actions are queued and waiting to be processed by the next action. + Runs that appear within an action are 1. currently being processed by the action, 2. have finished being processed by the action, or 3. were not processed by the action (usually because a previous action failed).