# Automate starting pipelines using triggers and filtering Automate starting pipelines using triggers and filtering Triggers allow you to configure your pipeline to start on a particular event type or filtered event type, such as when a change on a particular branch or pull request is detected. Triggers are configurable for source actions with connections that use the `CodeStarSourceConnection` action in CodePipeline, such as GitHub, Bitbucket, and GitLab. For more information about source actions that use connections, see [Add third-party source providers to pipelines using CodeConnections](pipelines-connections.md). Source actions, such as CodeCommit and S3, use automated change detection to start pipelines when a change is made. For more information, see [CodeCommit source actions and EventBridge](triggering.md). You specify triggers using the console or CLI. 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. + **Push** + Valid filter combinations are: + **Git tags** Include or exclude + **branches** Include or exclude + **branches \$1 file paths** Include or exclude + **Pull request** + Valid filter combinations are: + **branches** Include or exclude + **branches \$1 file paths** Include or exclude + **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 field definitions and further reference for triggers, see For a list of field definitions in the JSON structure, see [`triggers`](pipeline-requirements.md#pipeline.triggers). For filtering, regular expression patterns in glob format are supported as detailed in [Working with glob patterns in syntax](syntax-glob.md). **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](troubleshooting.md#troubleshooting-file-paths-filtering). ## Considerations for trigger filters The following considerations apply when using triggers. + You cannot add more than one trigger per source action. + You can add multiple filter types to a trigger. For an example, see [4: A trigger with two push filter types with conflicting includes and excludes](#example-filter-multiple-push). + 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) trigger configurations intersect. + For a filter that triggers your pipeline on pull request events, for the Closed pull request event type, the third-party repository provider for your connection might have a separate status for a merge event. For example, in Bitbucket, the Git event for a merge is not a pull request closure event. However, in GitHub, merging a pull request is a closure event. For more information, see [Pull request events for triggers by provider](#pipelines-filter-pullrequest-events). ## Pull request events for triggers by provider The following table provides a summary of the Git events, such as for pull request closure, that result in pull request event types by provider. **** | | Repository provider for your connection | PR event for trigger | Bitbucket | GitHub | GHES | GitLab | | --- | --- | --- | --- | --- | --- | --- | | Open - This option triggers the pipeline when a pull request is created for the branch/file path. | Creating a pull request results in an Opened Git event. | Creating a pull request results in an Opened Git event. | Creating a pull request results in an Opened Git event. | Creating a pull request results in an Opened Git event. | | Update - This option triggers the pipeline when a pull request revision is published for the branch/file path. | Publishing an update results in an Updated Git event. | Publishing an update results in an Updated Git event. | Publishing an update results in an Updated Git event. | Publishing an update results in an Updated Git event. | | Closed - This option triggers the pipeline when a pull request is closed for the branch/file path. | Merging a pull request in Bitbucket results in a Closed Git event. Important: Manually closing a pull request in Bitbucket without merging does not result in a Closed Git event. | Merging or manually closing a pull request results in a Closed Git event. | Merging or manually closing a pull request results in a Closed Git event. | Merging or manually closing a pull request results in a Closed Git event. | ## 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. A trigger can contain multiple filter types, such as two push filter types in the trigger configuration, and the push and pull request filter types will use an OR operation between them, meaning any match will start the pipeline. Similarly, each filter type can include multiple filters such as filePaths and branches; these filters will use an AND operation, meaning only a full match will start the pipeline. Each filter type can contain includes and excludes, where excludes take precedence over includes. If a branch or file path matches an exclude pattern, it will not trigger the pipeline, even if it also matches an include pattern. When a commit changes multiple files, each file is evaluated independently against the filter; if any changed file passes (matches an include and does not match an exclude), the pipeline will start. Names inside of the include/exclude, such as branch names, use an OR operation. The following list summarizes the operations for each part of the Git configuration object. For a list of field definitions in the JSON structure and a detailed reference for includes and excludes, see [`triggers`](pipeline-requirements.md#pipeline.triggers). **Example 1: A filter type with filters for branches and file paths (AND operation)** For a single filter type such as pull request, you can combine filters, and these filters will use an AND operation, meaning only a full match will start the pipeline. The following example shows a Git configuration for a push event type with two different filters (`filePaths` and `branches`). 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. In other words, the file path `common/app.js` is included for the filter, which starts the pipeline as an AND even if the branch `refs/heads/feature/triggers ` specified did not have an impact. ``` { "ref": "refs/heads/feature/triggers", ... "commits": [ { ... "modified": [ "common/app.js" ] ... } ] } ``` The following example shows an event for a trigger with the above configuration 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" ] ... } ] } ``` **Example 2: Excludes take precedence over includes** Within a single filter, excludes take precedence over includes. The following example shows a Git configuration with a single filter (`branches`) within the configuration object. This means that if a branch matches an exclude pattern (`feature-branch` in the example), the pipeline will not be triggered, even if it also matches an include pattern. If the include pattern matches and no exclude pattern matches, such as for the `main` branch, then the pipeline will be triggered. For the following example JSON: + Pushing a commit to the `main` branch will trigger the pipeline + Pushing a commit to the `feature-branch` branch will not trigger the pipeline. ``` { "branches": { "Includes": [ "main" ], "Excludes": [ "feature-branch" ] } ``` **Example 3: A trigger with push and pull request filter types (OR operation), filters for file paths and branches (AND operation), and includes/excludes (excludes take precedence)** Trigger configuration objects, such as a trigger that contains a push event type and a pull request event type, use an OR operation between the two event types. The following example shows a trigger configuration with a push event type with the `main` branch included and one pull request event type with the same branch `main` excluded. Additionally, the push event type has one file path `LICENSE.txt` excluded and one file path `README.MD` included. For the second event type, a pull request that is either `Closed` or `Created` on the `feature-branch` branch (included) starts the pipeline, and the pipeline does not start when creating or closing a pull request on the `feature-branch-2` or `main` branches (excluded). Within each event type, excludes take precedence over includes. For example, for a pull request event on the `feature-branch` branch (included for the pull request), the push event type excludes the `feature-branch` branch, so the push will not trigger the pipeline. For the following example, + Pushing a commit to the `main` branch (included) for the `README.MD` file path (included) will trigger the pipeline. + On the `feature-branch` branch (excluded), pushing a commit will not trigger the pipeline. + On the included branch, editing the `README.MD` file path (included) triggers the pipeline. + On the included branch, editing only the `LICENSE.TXT` file path (excluded) does not trigger the pipeline. However, if the same commit also changes `README.MD` (included), the pipeline will trigger because each file is evaluated independently. + On the `feature-branch` branch, closing a pull request will trigger the pipeline because `feature-branch` is included for the pull request event type and the event type CLOSED matches. The following image shows the configuration. ![\[An example trigger configuration with a push filter type and a pull request filter type\]](http://docs.aws.amazon.com/codepipeline/latest/userguide/images/example-trigger-filters-pushpluspullrequest.png) The following is the example JSON for the configuration. ``` "triggers": [ { "providerType": "CodeStarSourceConnection", "gitConfiguration": { "sourceActionName": "Source", "push": [ { "branches": { "includes": [ "main" ], "excludes": [ "feature-branch", "feature-branch-2" ] }, "filePaths": { "includes": [ "README.md" ], "excludes": [ "LICENSE.txt" ] } } ], "pullRequest": [ { "events": [ "CLOSED", "OPEN" ], "branches": { "includes": [ "feature-branch" ], "excludes": [ "feature-branch-2", "main" ] } } ] } } ] }, ``` **Example 4: A trigger with two push filter types with conflicting includes and excludes** The following image shows a push filter type specifying to filter on the tag `release-1` (included). A second push filter type is added specifying to filter on the branch `main` (included) and to not start for a push to the `feature*` branches (excluded). For the following example: + Pushing a release from the tag `release-1` (included for the first push filter) on the `feature-branch` branch (excluded as `feature*` for the second push filter) will trigger the pipeline because the two push filter types use an OR operation between them, and the first push filter (tag `release-1`) matches. + Pushing a release from the `main` branch (included for the second Push filter) will start the pipeline. The following example of the Edit page shows the two Push filter types and their configuration for includes and excludes. ![\[An example trigger configuration with a push filter type that includes the release-1 tag and a push filter type the includes the main* branch and excludes the feature* branches\]](http://docs.aws.amazon.com/codepipeline/latest/userguide/images/example-trigger-filters-pushtags-pushbranches.png) The following is the example JSON for the configuration. ``` "triggers": [ { "providerType": "CodeStarSourceConnection", "gitConfiguration": { "sourceActionName": "Source", "push": [ { "tags": { "includes": [ "release-1" ] } }, { "branches": { "includes": [ "main*" ], "excludes": [ "feature*" ] } } ] } } ] }, ``` **Example 5: Trigger configured while default action configuration BranchName is used for a manual start** The action configuration default `BranchName` field defines a single branch that will be used when the pipeline is started manually, while triggers with filters can be used for any branch or branches that you specify. The following is the example JSON for the action configuration showing the `BranchName` field. ``` { "name": "Source", "actions": [ { "name": "Source", "actionTypeId": { "category": "Source", "owner": "AWS", "provider": "CodeStarSourceConnection", "version": "1" }, "runOrder": 1, "configuration": { "BranchName": "main", "ConnectionArn": "ARN", "DetectChanges": "false", "FullRepositoryId": "owner-name/my-bitbucket-repo", "OutputArtifactFormat": "CODE_ZIP" }, "outputArtifacts": [ { "name": "SourceArtifact" } ], "inputArtifacts": [], "region": "us-west-2", "namespace": "SourceVariables" } ], ``` The following example action output shows the default branch main was used when the pipeline was manually started. ![\[An example action output page for a manually started pipeline\]](http://docs.aws.amazon.com/codepipeline/latest/userguide/images/example-source-action-manual.png) The following example action output shows the pull request and branch that was used for the trigger when filtered by pull request. ![\[An example action output page for a pipeline started with a trigger pull request filter type\]](http://docs.aws.amazon.com/codepipeline/latest/userguide/images/example-source-action-pr.png) # Add trigger on code push with no filter Add trigger on code push with no filter Triggers allow you to configure your pipeline to start on a particular event type, such as a code push or pull request. Triggers are configurable for source actions with connections that use the CodeStarSourceConnection action in CodePipeline, such as GitHub, Bitbucket, and GitLab. **Adding a trigger (console)** 1. Sign in to the AWS Management Console and open the CodePipeline console at [http://console.aws.amazon.com/codesuite/codepipeline/home](http://console.aws.amazon.com/codesuite/codepipeline/home). The names and status of all pipelines associated with your AWS account are displayed. 1. In **Name**, choose the name of the pipeline you want to edit. Otherwise, use these steps on the pipeline creation wizard. 1. On the pipeline details page, choose **Edit**. 1. On the **Edit** page, choose the source action you want to edit. Choose **Edit triggers**. Choose to add a trigger. 1. In **Trigger type**, choose **No filter**. # Add trigger with code push or pull request event types Add trigger with code push or pull request event types 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 trigger filters. **Note** The action configuration `BranchName` field defines a single branch, while triggers with filters can be used for any branch or branches that you specify. For a pipeline where triggers are used to filter branches by push or pull request, the pipeline won't use the default `BranchName` field branch in the action configuration. However, the branch in the `BranchName` field in the action configuration is the default when the pipeline is started manually. For an example, see [5: Trigger configured while default action configuration BranchName is used for a manual start](pipelines-triggers.md#example-filter-default-manual). 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. The supported event types for pull requests are the following. All other pull request events are ignored. + Opened + Updated + Closed (merged) **Note** Certain pull request event behavior can differ by provider. For details, see [Pull request events for triggers by provider](pipelines-triggers.md#pipelines-filter-pullrequest-events). The pipeline definition allows you to combine different filters within the same push trigger configuration. For details about the pipeline definition, see [Add filters for push and pull request event types (CLI)](#pipelines-filter-cli). For a list of field definitions, see [triggers](pipeline-requirements.md#pipeline.triggers) in the *Pipeline structure reference* in this guide. **Topics** + [ ## Add filters for push and pull request event types (console) ](#pipelines-filter-console) + [ ## Add filters for push and pull request event types (CLI) ](#pipelines-filter-cli) + [ ## Add filters for push and pull request event types (CloudFormation templates) ](#pipelines-filter-cfn) ## Add filters for push and pull request event types (console) You can use the console to add filters for push events and include or exclude branches or file paths. **Add filters (console)** 1. Sign in to the AWS Management Console and open the CodePipeline console at [http://console.aws.amazon.com/codesuite/codepipeline/home](http://console.aws.amazon.com/codesuite/codepipeline/home). The names and status of all pipelines associated with your AWS account are displayed. 1. In **Name**, choose the name of the pipeline you want to edit. Otherwise, use these steps on the pipeline creation wizard. 1. On the pipeline details page, choose **Edit**. 1. On the **Edit** page, choose the source action you want to edit. Choose **Edit triggers**. Choose **Specify filter**. 1. In **Event type**, choose **Push** from the following options. + Choose **Push** to start the pipeline when a change is pushed to your source repository. Choosing this enables the fields to specify filters for branches and file paths or Git tags. + Choose **Pull request** to start the pipeline when a pull request is opened, updated, or closed in your source repository. Choosing this enables the fields to specify filters for destination branches and file paths. 1. Under **Push**, in **Filter type**, choose one of the following options. + Choose **Branch** to specify the branches in your source repository that the trigger monitors in order to know when to start a workflow run. In **Include**, enter patterns for branch names in glob format that you want to specify for the trigger configuration to start your pipeline on changes in the specified branches. In **Exclude**, enter the regex patterns for branch names in glob format that you want to specify for the trigger configuration to ignore and to not start your pipeline on changes in the specified branches. See [Working with glob patterns in syntax](syntax-glob.md) for more information. **Note** If the include and exclude both have the same pattern, then the default is to exclude the pattern. You can use glob patterns to define your branch names. For example, use `main*` to match all branches beginning with `main`. See [Working with glob patterns in syntax](syntax-glob.md) for more information. For a push trigger, specify the branches you're pushing *to*, that is, the *destination* branches. For a pull request trigger, specify destination branches you're opening pull request to. + (Optional) Under **File paths**, specify file paths for your trigger. Enter the names in **Include** and **Exclude** as appropriate. You can use glob patterns to define your file path names. For example, use `prod*` to match all file paths beginning with `prod`. See [Working with glob patterns in syntax](syntax-glob.md) for more information. + Choose **Tags** to configure the pipeline trigger configuration to start with Git tags. In **Include**, enter patterns for tag names in glob format that you want to specify for the trigger configuration to start your pipeline on release of the specified tag or tags. In **Exclude**, enter the regex patterns for tag names in glob format that you want to specify for the trigger configuration to ignore and to not start your pipeline on release of the specified tag or tags. If the include and exclude both have the same tag pattern, then the default is to exclude the tag pattern. 1. Under **Push**, in **Filter type**, choose one of the following options. + Choose **Branch** to specify the branches in your source repository that the trigger monitors in order to know when to start a workflow run. In **Include**, enter patterns for branch names in glob format that you want to specify for the trigger configuration to start your pipeline on changes in the specified branches. In **Exclude**, enter the regex patterns for branch names in glob format that you want to specify for the trigger configuration to ignore and to not start your pipeline on changes in the specified branches. See [Working with glob patterns in syntax](syntax-glob.md) for more information. **Note** If the include and exclude both have the same pattern, then the default is to exclude the pattern. You can use glob patterns to define your branch names. For example, use `main*` to match all branches beginning with `main`. See [Working with glob patterns in syntax](syntax-glob.md) for more information. For a push trigger, specify the branches you're pushing *to*, that is, the *destination* branches. For a pull request trigger, specify destination branches you're opening pull request to. + (Optional) Under **File paths**, specify file paths for your trigger. Enter the names in **Include** and **Exclude** as appropriate. You can use glob patterns to define your file path names. For example, use `prod*` to match all file paths beginning with `prod`. See [Working with glob patterns in syntax](syntax-glob.md) for more information. + Choose **Pull request** to configure the pipeline trigger configuration to start with pull request events that you specify. ## Add filters for push and pull request event types (CLI) You can update the pipeline JSON to add filters for triggers. To use the AWS CLI to create or update your pipeline, use the `create-pipeline` or `update-pipeline` command. The following example JSON structure provides a reference for the field definitions under `create-pipeline`. For a list of field definitions, see [triggers](pipeline-requirements.md#pipeline.triggers) in the *Pipeline structure reference* in this guide. ``` { "pipeline": { "name": "MyServicePipeline", "triggers": [ { "provider": "Connection", "gitConfiguration": { "sourceActionName": "ApplicationSource", "push": [ { "filePaths": { "includes": [ "projectA/**", "common/**/*.js" ], "excludes": [ "**/README.md", "**/LICENSE", "**/CONTRIBUTING.md" ] }, "branches": { "includes": [ "feature/**", "release/**" ], "excludes": [ "mainline" ] }, "tags": { "includes": [ "release-v0", "release-v1" ], "excludes": [ "release-v2" ] } } ], "pullRequest": [ { "events": [ "CLOSED" ], "branches": { "includes": [ "feature/**", "release/**" ], "excludes": [ "mainline" ] }, "filePaths": { "includes": [ "projectA/**", "common/**/*.js" ], "excludes": [ "**/README.md", "**/LICENSE", "**/CONTRIBUTING.md" ] } } ] } } ], "stages": [ { "name": "Source", "actions": [ { "name": "ApplicationSource", "configuration": { "BranchName": "mainline", "ConnectionArn": "arn:aws:codestar-connections:eu-central-1:111122223333:connection/fe9ff2e8-ee25-40c9-829e-65f8EXAMPLE", "FullRepositoryId": "monorepo-example", "OutputArtifactFormat": "CODE_ZIP" } } ] } ] } } ``` ## Add filters for push and pull request event types (CloudFormation templates) You can update the pipeline resource in CloudFormation to add trigger filtering. The following example template snippet provides a YAML reference for triggers field definitions. For a list of field definitions, see [triggers](pipeline-requirements.md#pipeline.triggers) in the *Pipeline structure reference* in this guide. For a full template example for a connection source and trigger filter configuration, see [Pipeline with two stages and trigger configuration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codepipeline-pipeline.html#aws-resource-codepipeline-pipeline--examples--Pipeline_with_two_stages_and_trigger_configuration) in the* CloudFormation User Guide*. ``` pipeline: name: MyServicePipeline executionMode: PARALLEL triggers: - provider: CodeConnection gitConfiguration: sourceActionName: ApplicationSource push: - filePaths: includes: - projectA/** - common/**/*.js excludes: - '**/README.md' - '**/LICENSE' - '**/CONTRIBUTING.md' branches: includes: - feature/** - release/** excludes: - mainline - tags: includes: - release-v0 - release-v1 excludes: - release-v2 pullRequest: - events: - CLOSED branches: includes: - feature/** - release/** excludes: - mainline filePaths: includes: - projectA/** - common/**/*.js excludes: - '**/README.md' - '**/LICENSE' - '**/CONTRIBUTING.md' stages: - name: Source actions: - name: ApplicationSource configuration: BranchName: mainline ConnectionArn: arn:aws:codestar-connections:eu-central-1:111122223333:connection/fe9ff2e8-ee25-40c9-829e-65f85EXAMPLE FullRepositoryId: monorepo-example OutputArtifactFormat: CODE_ZIP ``` # Add trigger to turn off change detection Add trigger to turn off change detection Triggers allow you to configure your pipeline to start on a particular event type, such as a code push or pull request. Triggers are configurable for source actions with connections that use the `CodeStarSourceConnection` action in CodePipeline, such as GitHub, Bitbucket, and GitLab. **Adding a trigger to turn off change detection (console)** 1. Sign in to the AWS Management Console and open the CodePipeline console at [http://console.aws.amazon.com/codesuite/codepipeline/home](http://console.aws.amazon.com/codesuite/codepipeline/home). The names and status of all pipelines associated with your AWS account are displayed. 1. In **Name**, choose the name of the pipeline you want to edit. Otherwise, use these steps on the pipeline creation wizard. 1. On the pipeline details page, choose **Edit**. 1. On the **Edit** page, choose the source action you want to edit. Choose **Edit triggers**. Choose to add a trigger. 1. In **Trigger type**, choose **Do not detect changes**.