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.

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

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+0) 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.

Example: A trigger with a schedule and branches

The following example shows a trigger that starts a workflow run at 6:15 pm (UTC+0) 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.

Example: A trigger with a schedule, a push, and branches

The following example shows a trigger that starts a workflow run at midnight (UTC+0) every day, and whenever code is pushed to the main branch.

In this example:

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.

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:

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.

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:

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