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.
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.
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 + file paths
Include or exclude
-
-
-
Pull request
-
Valid filter combinations are:
-
branches
Include or exclude
-
branches + 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.
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.
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 .
-
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.
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, and
these will use an AND operation between them, meaning only a full match will start the
pipeline. Names inside of the include/exclude, such as branch names, use an OR
operation. If there is a conflict such as between two Push filters such as where one
includes the main
branch and one excludes it, then the default is to
exclude. 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.
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: Includes and excludes use an AND operation between them
Trigger filters, such as branch in a single pull request event type, use an AND
operation between the includes and excludes. This allows you to configure multiple
triggers to start the execution for the same pipeline. The following example shows a
trigger configuration with a single filter type (branches
) in the
configuration object for a push event. The Includes
and
Excludes
operations will be AND’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.
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 (AND operation)
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).The Includes
and Excludes
operations
will be AND’d, with a conflict defaulting to the exclude. For example, for a pull
request event on the feature-branch
branch (included for the pull
request) while the feature-branch
branch is excluded for the push event
type, so the default will be to exclude.
For the following example,
-
Pushing a commit to the
main
branch (included) for theREADME.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 the
LICENSE.TXT
file path (excluded) does not trigger the pipeline. -
On the
feature-branch
branch, closing a pull request for theREADME.MD
file path (included for the push event) will not trigger the pipeline because the push event type specifies thefeature-branch
branch as excluded and so the conflict defaults to the exclude.
The following image shows the configuration.

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 thefeature-branch
branch (excluded asfeature*
for the second push filter) will not trigger the pipeline because the two event types will be AND'd. -
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.

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.

The following example action output shows the pull request and branch that was used for the trigger when filtered by pull request.
