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).
# 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.
------