Automate starting pipelines using triggers and filtering

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"
      ]
      ...
    }
  ]
}

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:

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

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,

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"
                                ]
                            }
                        }
                    ]
                }
            }
        ]
    },

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:

The following example of the Edit page shows the two Push filter types and their configuration for includes and excludes.

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.