A common trigger configuration Learn about considerations when setting up triggers with branches Adding a push, pull, or schedule trigger Examples of triggers

Working with triggers

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.

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.

A common trigger configuration

This section describes how to set up triggers for a common software release and branching strategy.

Software release and branching strategy:

You have application code in a source repository.
Your main branch contains finalized code that is always release-ready.
Your software developers make their changes in feature branches off the main branch.
Your software developers create a pull request asking to merge their feature branch into main when their feature is ready.

You want this pull request to start a workflow automatically that builds and tests—but does not deploy—the application using the files on the software developer's feature branch.
You software developers check the build and the tests to make sure everythying looks good. They then merge the pull request into the main branch.

You want the merge to automatically start a workflow automatically that builds and deploys your application code.

Proposed workflow/trigger configuration:

Given the software branching strategy outlined previously, you might want to use two workflows:

Workflow 1 builds and tests your application when a pull request is created or revised.
Workflow 2 builds and deploys your application when a pull request is merged.

Workflow 1 would look like this:


Triggers:      
  - Type: PULLREQUEST
    Branches:
      - main
    Events:
      - OPEN
      - REVISION
Actions:
  BuildAction:
    instructions-for-building-the-app
  TestAction:
    instructions-for-test-the-app

The previous trigger code automatically starts a workflow run whenever a software developer creates a pull request (or modifies one) asking to merge their feature branch to the main branch. CodeCatalyst starts a workflow run using the code in the source branch (that is, the developer's feature branch). The workflow builds and deploys the application.

Workflow 2 would look like this:


Triggers:      
  - Type: PUSH
    Branches:
      - main
Actions:
  BuildAction:
    instructions-for-building-the-app
  DeployAction:
    instructions-for-deploying-the-app

In the previous trigger code, when a merge to main occurs, the PUSH trigger is activated. CodeCatalyst starts a workflow run using the code in the main branch (which now includes the code from the pull request). The workflow builds and deploys the application.

For instructions on adding triggers to a workflow definition file, see Adding a push, pull, or schedule trigger.

For more examples of triggers and additional explanations, see Examples of triggers.

Trigger considerations when branching

This section describes some of the main considerations when setting up triggers that include branches.

Consideration 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
```
Consideration 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.
Consideration 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).
Consideration 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 if use the files in test). Review Considerations 1 and 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 Considerations 1 and 3 to understand why.

Adding a push, pull, or schedule trigger

Use the following instructions to add a push, pull, or schedule trigger to your workflow.

Visual

To add a trigger (visual editor)

Open the CodeCatalyst console at https://codecatalyst.aws/.
Choose your project.
In the navigation pane, choose CI/CD, and then choose Workflows.
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.
Choose Edit.
Choose Visual.
In the workflow diagram, choose the Source and Triggers box.
In the configuration pane, Choose Add trigger.

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.

For examples, see Examples of triggers.

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 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 of triggers.

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

Minutes	Hours	Days of month	Month	Days of week	Year	Meaning
0	0	?	*	MON-FRI	*	Runs a workflow at midnight (UTC+0) every Monday through Friday.
0	2	*	*	?	*	Runs a workflow at 2:00 am (UTC+0) every day.
15	22	*	*	?	*	Runs a workflow at 10:15 pm (UTC+0) every day.
0/30	22-2	?	*	SAT-SUN	*	Runs a workflow every 30 minutes Saturday through Sunday between 10:00 pm on the starting day and 2:00 am on the following day (UTC+0).
45	13	L	*	?	2023-2027	Runs a workflow at 1:45 pm (UTC+0) on the last day of the month between the years 2023 and 2027 inclusive.

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 in the Amazon EventBridge User Guide. Cron expressions in EventBridge and CodeCatalyst work exactly the same way.

For examples of schedule triggers, see Examples of triggers.

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.
The branch you're pulling from (for pull request triggers). For more information, see Example: A simple pull request trigger.
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.

For more information about branches and triggers, see Trigger considerations when branching.

For more examples, see Examples of triggers.

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 of triggers.

(Optional) Choose Validate to validate the workflow's YAML code before committing.
Choose Commit, enter a commit message, and choose Commit again.

YAML

To add a trigger (YAML editor)

Open the CodeCatalyst console at https://codecatalyst.aws/.
Choose your project.
In the navigation pane, choose CI/CD, and then choose Workflows.
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.
Choose Edit.
Choose YAML.
Add a Triggers section and underlying properties using the following example as a guide. For more information, see the Triggers in the Workflow definition reference.

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.

For more examples of push, pull request, and schedule triggers, see Examples of triggers.
(Optional) Choose Validate to validate the workflow's YAML code before committing.
Choose Commit, enter a commit message, and choose Commit again.

Examples of triggers

The following examples show how to add different types of triggers in the workflow definition file.

Topics

Example: A simple code push trigger
Example: A simple 'push to main' trigger
Example: A simple pull request trigger
Example: A simple schedule trigger
Example: A trigger with a schedule and branches
Example: A trigger with a schedule, a push, and branches
Example: A trigger with a pull and branches
Example: A trigger with a pull, branches, and a 'CLOSED' event
Example: A trigger with a push, branches, and files

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.

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:

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.

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\/.*

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Working with sources

Working with variables