Filter triggers on code push or pull requests - AWS CodePipeline
Considerations for trigger filtersExamples for trigger filters

Filter triggers on code push or pull requests

You can configure filters for pipeline triggers to have pipeline executions started for different Git events, such as tag or branch push, changes in specific file paths, a pull request opened into a specific branch, and so on. You can use the AWS CodePipeline console or the create-pipeline and update-pipeline commands in the AWS CLI to configure triggers' filters.

You can specify filters for the following trigger types:

  • Push

    A push trigger starts a pipeline when a change is pushed to your source repository. The execution will use the commit from the branch that you're pushing to (that is, the destination branch). You can filter push triggers on branches, file paths, or Git tags.

  • Pull request

    A pull request trigger starts a pipeline when a pull request is opened, updated, or closed in your source repository. The execution will use the commit from the source branch that you're pulling from (that is, the source branch). You can filter pull request triggers on branches and file paths.

    Note

    The supported event types for pull requests are opened, updated, or closed (merged). All other pull request events are ignored.

The pipeline definition allows you to combine different filters within the same push trigger configuration. For details about the pipeline definition, see Trigger filtering in the pipeline JSON (CLI). Valid combinations are:

  • tags

  • branches

  • branches + file paths

You specify filter types as follows:

  • No filter

    This trigger configuration starts your pipeline on any push to the default branch specified as part of action configuration.

  • Specify filter

    You add a filter that starts your pipeline on a specific filter, such as on branch names for a code push, and fetches the exact commit. This also configures the pipeline not to start automatically on any change.

  • Do not detect changes

    This does not add a trigger and the pipeline does not start automatically on any change.

The following table provides valid filter options for each event type. The table also shows which trigger configurations default to true or false for automatic change detection in the action configuration.

Trigger configuration Event type Filter options Detect changes
Add a trigger – no filter none none true
Add a trigger – filter on code push push event Git tags, branches, file paths false
Add a trigger – filter for pull requests pull requests branches, file paths false
No trigger – do not detect none none false
Note

This trigger type uses automated change detection (as the Webhook trigger type). The source action providers that use this trigger type are connections configured for code push (Bitbucket Cloud, GitHub, GitHub Enterprise Server, GitLab.com, and GitLab self-managed).

For filtering, regular expression patterns in glob format are supported as detailed in Working with glob patterns in syntax.

Note

In certain cases, for pipelines with triggers that are filtered on file paths, the pipeline might not start when a branch with a file path filter is first created. For more information, see Pipelines with connections that use trigger filtering by file paths might not start at branch creation.

Topics

Considerations for trigger filters

The following considerations apply when using triggers.

  • For a trigger with branch and file paths filters, when pushing the branch for the first time, the pipeline won't run since there is not access to the list of files changed for the newly created branch.

  • Merging a pull request might trigger two pipeline executions, in cases where push (branches filter) and pull request (branches filter) triggers configurations intersect.

Examples for trigger filters

For a Git configuration with filters for push and pull request event types, the specified filters might conflict with each other. The following are examples of valid filter combinations for push and pull request events.

You can combine filters within a single configuration object, and these filters will use an AND operation, meaning only a full match will start the pipeline. The following example shows a Git configuration with two different filters (filePaths and branches) within the “configuration object” and not a single filter. In the following example, filePaths will be AND’ed with branches:

{
  "filePaths": {
    "includes": ["common/**/*.js"]
  },
  "branches": {
    "includes": ["feature/**"]
  }
}

With the Git configuration above, this example shows an event that will start the pipeline execution because the AND operation succeeds.

{
  "ref": "refs/heads/feature/triggers",
  ...
  "commits": [
    {
      ...
      "modified": [
        "common/app.js"
      ]
      ...
    }
  ]
}

This example shows an event that will not start the pipeline execution because the branch is able to filter, but the file path is not.

{
   "ref": "refs/heads/feature/triggers",
  ...
  "commits": [
    {
      ...
      "modified": [
        "src/Main.java"
      ]
      ...
    }
  ]
}

At the same time, trigger configuration objects within the push array use an OR operation. This allows you to configure multiple triggers to start the execution for the same pipeline. The following example shows a Git configuration with a single filter (branches) within the configuration object. The Includes and Excludes operations will be OR’ed, meaning that if a branch matches an exclude pattern (such as feature-branch in the example), the pipeline will not be triggered unless an include also matches. If the include pattern matches, such as for the main branch, then the pipeline will be triggered.

{
  "branches": {
      "Includes": [
          "main"
      ],
      "Excludes": [
          "feature-branch"
      ]
   }

For a list of field definitions in the JSON structure, see Trigger filtering in the pipeline JSON (CLI).