# Use webhooks with AWS CodeBuild AWS CodeBuild supports webhook integration with GitHub, GitHub Enterprise Server, GitLab, GitLab Self Managed, and Bitbucket. **Topics** + [Best practices for using webhooks with AWS CodeBuild](#webhook-best-practices) + [Bitbucket webhook events](bitbucket-webhook.md) + [GitHub global and organization webhooks](github-global-organization-webhook.md) + [GitHub manual webhooks](github-manual-webhook.md) + [GitHub webhook events](github-webhook.md) + [GitLab group webhooks](gitlab-group-webhook.md) + [GitLab manual webhooks](gitlab-manual-webhook.md) + [GitLab webhook events](gitlab-webhook.md) + [Buildkite manual webhooks](buildkite-manual-webhook.md) + [Pull request comment approval](pull-request-build-policy.md) ## Best practices for using webhooks with AWS CodeBuild For projects that use public repositories to setup webhooks, we recommend the following options: Setup `ACTOR_ACCOUNT_ID` filters Add `ACTOR_ACCOUNT_ID` filters to your project’s webhook filter groups to specify which users can trigger a build. Every webhook event delivered to CodeBuild comes with sender information that specifies the actor's identifier. CodeBuild will filter the webhooks based on the regular expression pattern provided in the filters. You can specify the specific users that are allowed to trigger builds with this filter. For more information, see [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md). Setup `FILE_PATH` filters Add `FILE_PATH` filters to your project’s webhook filter groups to include or exclude the files that can trigger a build when changed. For example, you can deny build requests for changes to the `buildspec.yml` file using a regular expression pattern such as `^buildspec.yml$`, along with the `excludeMatchedPattern` property. For more information, see [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md). Scope down the permissions for your build IAM role Builds triggered by a webhook use the IAM service role specified in the project. We recommend setting the permissions in the service role to the minimum set of permissions required to run the build. For example, in a test and deploy scenario, create one project for testing and another project for deployment. The testing project accepts webhook builds from the repository, but provides no write permissions to your resources. The deployment project provides write permissions to your resources, and the webhook filter is configured to only allow trusted users to trigger builds. Use an inline or an Amazon S3 stored buildspec If you define your buildspec inline within the project itself, or store the buildspec file in an Amazon S3 bucket, the buildspec file is only visible to the project owner. This prevents pull requests from making code changes to the buildspec file and triggering unwanted builds. For more information, see [ProjectSource.buildspec](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html#CodeBuild-Type-ProjectSource-buildspec) in the *CodeBuild API Reference*. # Bitbucket webhook events You can use webhook filter groups to specify which Bitbucket webhook events trigger a build. For example, you can specify that a build is only triggered for changes to specific branches. You can create one or more webhook filter groups to specify which webhook events trigger a build. A build is triggered if any filter group evaluates to true, which occurs when all the filters in the group evaluate to true. When you create a filter group, you specify: **An event** For Bitbucket, you can choose one or more of the following events: + `PUSH` + `PULL_REQUEST_CREATED` + `PULL_REQUEST_UPDATED` + `PULL_REQUEST_MERGED` + `PULL_REQUEST_CLOSED` The webhook's event type is in its header in the `X-Event-Key` field. The following table shows how `X-Event-Key` header values map to the event types. You must enable the `merged` event in your Bitbucket webhook setting if you create a webhook filter group that uses the `PULL_REQUEST_MERGED` event type. You must also enable the `declined` event in your Bitbucket webhook setting if you create a webhook filter group that uses the `PULL_REQUEST_CLOSED` event type. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/bitbucket-webhook.html) For `PULL_REQUEST_MERGED`, if a pull request is merged with the squash strategy and the pull request branch is closed, the original pull request commit no longer exists. In this case, the `CODEBUILD_WEBHOOK_MERGE_COMMIT` environment variable contains the identifier of the squashed merge commit. **One or more optional filters** Use a regular expression to specify a filter. For an event to trigger a build, every filter within the group associated with it must evaluate to true. `ACTOR_ACCOUNT_ID` (`ACTOR_ID` in the console) A webhook event triggers a build when a Bitbucket account ID matches the regular expression pattern. This value appears in the `account_id` property of the `actor` object in the webhook filter payload. `HEAD_REF` A webhook event triggers a build when the head reference matches the regular expression pattern (for example, `refs/heads/branch-name` and `refs/tags/tag-name`). A `HEAD_REF` filter evaluates the Git reference name for the branch or tag. The branch or tag name appears in the `name` field of the `new` object in the `push` object of the webhook payload. For pull request events, the branch name appears in the `name` field in the `branch` object of the `source` object in the webhook payload. `BASE_REF` A webhook event triggers a build when the base reference matches the regular expression pattern. A `BASE_REF` filter works with pull request events only (for example, `refs/heads/branch-name`). A `BASE_REF` filter evaluates the Git reference name for the branch. The branch name appears in the `name` field of the `branch` object in the `destination` object in the webhook payload. `FILE_PATH` A webhook triggers a build when the path of a changed file matches the regular expression pattern. `COMMIT_MESSAGE` A webhook triggers a build when the head commit message matches the regular expression pattern. `WORKFLOW_NAME` A webhook triggers a build when the workflow name matches the regular expression pattern. **Note** You can find the webhook payload in the webhook settings of your Bitbucket repository. **Topics** + [Filter Bitbucket webhook events (console)](bitbucket-webhook-events-console.md) + [Filter Bitbucket webhook events (SDK)](bitbucket-webhook-events-sdk.md) + [Filter Bitbucket webhook events (CloudFormation)](bitbucket-webhook-events-cfn.md) # Filter Bitbucket webhook events (console) To use the AWS Management Console to filter webhook events: 1. Select **Rebuild every time a code change is pushed to this repository** when you create your project. 1. From **Event type**, choose one or more events. 1. To filter when an event triggers a build, under **Start a build under these conditions**, add one or more optional filters. 1. To filter when an event is not triggered, under **Don't start a build under these conditions**, add one or more optional filters. 1. Choose **Add filter group** to add another filter group. For more information, see [Create a build project (console)](create-project.md#create-project-console) and [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *AWS CodeBuild API Reference*. In this example, a webhook filter group triggers a build for pull requests only: ![\[A webhook filter group that triggers a build for pull requests only.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-bitbucket.png) Using an example of two filter groups, a build is triggered when one or both evaluate to true: + The first filter group specifies pull requests that are created or updated on branches with Git reference names that match the regular expression `^refs/heads/main$` and head references that match `^refs/heads/branch1!`. + The second filter group specifies push requests on branches with Git reference names that match the regular expression `^refs/heads/branch1$`. ![\[An example of two filter groups.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-head-base-regexes-bitbucket.png) In this example, a webhook filter group triggers a build for all requests except tag events. ![\[A webhook filter group that triggers a build for all requests except tag events.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-exclude-bitbucket.png) In this example, a webhook filter group triggers a build only when files with names that match the regular expression `^buildspec.*` change. ![\[A webhook filter group that triggers a build only when files with names that match the regular expression specified.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-regex.png) In this example, a webhook filter group triggers a build only when files are changed in `src` or `test` folders. ![\[A webhook filter group that triggers a build only when files are changed in specified folders.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-combined-regex.png) In this example, a webhook filter group triggers a build only when a change is made by a Bitbucket user who does not have an account ID that matches the regular expression `actor-account-id`. **Note** For information about how to find your Bitbucket account ID, see https://api.bitbucket.org/2.0/users/*user-name*, where *user-name* is your Bitbucket user name. ![\[A webhook filter group that triggers a build only when a change is made by a Bitbucket user who does not have an account ID.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-actor-bitbucket.png) In this example, a webhook filter group triggers a build for a push event when the head commit message matches the regular expression `\[CodeBuild\]`. ![\[A webhook filter group that triggers a build for a push event when the head commit message matches the regular expression.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-commit-message.png) # Filter Bitbucket webhook events (SDK) To use the AWS CodeBuild SDK to filter webhook events, use the `filterGroups` field in the request syntax of the `CreateWebhook` or `UpdateWebhook` API methods. For more information, see [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *CodeBuild API Reference*. To create a webhook filter that triggers a build for pull requests only, insert the following into the request syntax: ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED, PULL_REQUEST_CLOSED" } ] ] ``` To create a webhook filter that triggers a build for specified branches only, use the `pattern` parameter to specify a regular expression to filter branch names. Using an example of two filter groups, a build is triggered when one or both evaluate to true: + The first filter group specifies pull requests that are created or updated on branches with Git reference names that match the regular expression `^refs/heads/main$` and head references that match `^refs/heads/myBranch$`. + The second filter group specifies push requests on branches with Git reference names that match the regular expression `^refs/heads/myBranch$`. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_CLOSED" }, { "type": "HEAD_REF", "pattern": "^refs/heads/myBranch$" }, { "type": "BASE_REF", "pattern": "^refs/heads/main$" } ], [ { "type": "EVENT", "pattern": "PUSH" }, { "type": "HEAD_REF", "pattern": "^refs/heads/myBranch$" } ] ] ``` You can use the `excludeMatchedPattern` parameter to specify which events do not trigger a build. In this example, a build is triggered for all requests except tag events. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED, PULL_REQUEST_CLOSED" }, { "type": "HEAD_REF", "pattern": "^refs/tags/.*", "excludeMatchedPattern": true } ] ] ``` You can create a filter that triggers a build only when a change is made by a Bitbucket user with account ID `actor-account-id`. **Note** For information about how to find your Bitbucket account ID, see https://api.bitbucket.org/2.0/users/*user-name*, where *user-name* is your Bitbucket user name. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED, PULL_REQUEST_CLOSED" }, { "type": "ACTOR_ACCOUNT_ID", "pattern": "actor-account-id" } ] ] ``` You can create a filter that triggers a build only when files with names that match the regular expression in the `pattern` argument change. In this example, the filter group specifies that a build is triggered only when files with a name that matches the regular expression `^buildspec.*` change. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH" }, { "type": "FILE_PATH", "pattern": "^buildspec.*" } ] ] ``` In this example, the filter group specifies that a build is triggered only when files are changed in `src` or `test` folders. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH" }, { "type": "FILE_PATH", "pattern": "^src/.+|^test/.+" } ] ] ``` You can create a filter that triggers a build only when the head commit message matches the regular expression in the pattern argument. In this example, the filter group specifies that a build is triggered only when the head commit message of the push event matches the regular expression `\[CodeBuild\]`. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH" }, { "type": "COMMIT_MESSAGE", "pattern": "\[CodeBuild\]" } ] ] ``` # Filter Bitbucket webhook events (CloudFormation) To use an CloudFormation template to filter webhook events, use the AWS CodeBuild project's `FilterGroups` property. The following YAML-formatted portion of an CloudFormation template creates two filter groups. Together, they trigger a build when one or both evaluate to true: + The first filter group specifies pull requests are created or updated on branches with Git reference names that match the regular expression `^refs/heads/main$` by a Bitbucket user who does not have account ID `12345`. + The second filter group specifies push requests are created on branches with Git reference names that match the regular expression `^refs/heads/.*`. + The third filter group specifies a push request with a head commit message matching the regular expression `\[CodeBuild\]`. ``` CodeBuildProject: Type: AWS::CodeBuild::Project Properties: Name: MyProject ServiceRole: service-role Artifacts: Type: NO_ARTIFACTS Environment: Type: LINUX_CONTAINER ComputeType: BUILD_GENERAL1_SMALL Image: aws/codebuild/standard:5.0 Source: Type: BITBUCKET Location: source-location Triggers: Webhook: true FilterGroups: - - Type: EVENT Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED - Type: BASE_REF Pattern: ^refs/heads/main$ ExcludeMatchedPattern: false - Type: ACTOR_ACCOUNT_ID Pattern: 12345 ExcludeMatchedPattern: true - - Type: EVENT Pattern: PUSH - Type: HEAD_REF Pattern: ^refs/heads/.* - Type: FILE_PATH Pattern: READ_ME ExcludeMatchedPattern: true - - Type: EVENT Pattern: PUSH - Type: COMMIT_MESSAGE Pattern: \[CodeBuild\] - Type: FILE_PATH Pattern: ^src/.+|^test/.+ ``` # GitHub global and organization webhooks You can use CodeBuild GitHub global or organization webhooks to start builds on webhook events from any repository within a GitHub organization or enterprise. Global and organization webhooks work with any of the existing GitHub webhook event types, and can be configured by adding a scope configuration when creating a CodeBuild webhook. You can also use global and organization webhooks to [set up self-hosted GitHub Action runners within CodeBuild](action-runner.md) in order to receive `WORKFLOW_JOB_QUEUED` events from multiple repositories within a single project. **Topics** + [Set up a global or organization GitHub webhook](github-global-organization-webhook-setup.md) + [Filter GitHub global or organization webhook events (console)](github-global-organization-webhook-events-console.md) + [Filter GitHub organization webhook events (CloudFormation)](github-organization-webhook-events-cfn.md) # Set up a global or organization GitHub webhook The high-level steps to set up a global or organization GitHub webhook are as follows. For more information about global and organization GitHub webhooks, see [GitHub global and organization webhooks](github-global-organization-webhook.md). 1. Set your project's source location to `CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION`. 1. In the webhook's scope configuration, set the scope to either `GITHUB_ORGANIZATION` or `GITHUB_GLOBAL` depending on whether it should be an organization or [ global webhook](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/managing-global-webhooks). For more information, see [ Types of webhooks](https://docs.github.com/en/webhooks/types-of-webhooks). 1. Specify a name as part of the webhook's scope configuration. For organization webhooks, this is the organization name, and for global webhooks this is the enterprise name. **Note** If the project's source type is `GITHUB_ENTERPRISE`, you will also need to specify a domain as part of the webhook scope configuration. 1. (Optional) If you would only like to receive webhook events for specific repositories within your organization or enterprise, you can specify `REPOSITORY_NAME` as a filter when creating the webhook. 1. If you are creating an organization webhook, ensure that CodeBuild has permissions to create organization level webhooks within GitHub. You can create a GitHub personal access token with organization webhook permissions, or use CodeBuild OAuth. For more information, see [GitHub and GitHub Enterprise Server access token](access-tokens-github.md). Note that organization webhooks work with any of the existing GitHub webhook event types. 1. If you are creating a global webhook, the webhook will need to be created manually. For more information about how to manually create a webhook within GitHub, see [GitHub manual webhooks](github-manual-webhook.md). Note that global webhooks only support the `WORKFLOW_JOB_QUEUED` event type. For more information, see [Tutorial: Configure a CodeBuild-hosted GitHub Actions runner](action-runner.md). # Filter GitHub global or organization webhook events (console) When creating a GitHub project through the console, select the following options to create a GitHub global or organization webhook within the project. For more information about global and organization GitHub webhooks, see [GitHub global and organization webhooks](github-global-organization-webhook.md). 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. Create a build project. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md). + In **Source**: + For **Source provider**, choose **GitHub** or **GitHub Enterprise**. + For **Repository**, choose **GitHub scoped webhook**. The GitHub repository will automatically be set to `CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION`, which is the required source location for global and organization webhooks. **Note** If you are using organization webhooks, make sure that CodeBuild has permissions to create organization level webhooks within GitHub. If you're using an [existing OAuth connection](oauth-app-github.md), you may need to regenerate the connection in order to grant CodeBuild this permission. Alternatively, you can create the webhook manually using the [CodeBuild manual webhooks feature](github-manual-webhook.md). Note that if you have an existing GitHub OAuth token and would like to add additional organization permissions, you can [revoke the OAuth token's permission](https://docs.github.com/en/apps/oauth-apps/using-oauth-apps/reviewing-your-authorized-oauth-apps) and reconnect the token through the CodeBuild console. ![\[The configuration of GitHub scoped webhook.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-organization-webhook-source.png) + In **Primary source webhook events**: + For **Scope type**, choose **Organization level** if you're creating an organization webhook or **Enterprise level** if you're creating a global webhook. + For **Name**, enter either the enterprise or organization name, depending on if the webhook is a global or organization webhook. If the project's source type is `GITHUB_ENTERPRISE`, you also need to specify a domain as part of the webhook organization configuration. For example, if the URL of your organization is **https://domain.com/orgs/org-name**, then the domain is **https://domain.com**. **Note** This name cannot be changed after the webhook has been created. To change the name, you can delete and re-create the webhook. If you want to remove the webhook entirely, you can also update the project source location to a GitHub repository. ![\[The configuration of global or organization webhooks.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-organization-webhook-primary-events.png) + (Optional) In **Webhook event filter groups**, you can specify which [events you would like to trigger a new build](github-webhook.md). You can also specify `REPOSITORY_NAME` as a filter to only trigger builds on webhook events from specific repositories. ![\[A filter that only triggers builds on webhook events from specific repositories.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-organization-webhook-filter-groups.png) You can also set the event type to `WORKFLOW_JOB_QUEUED` to set up self-hosted GitHub Actions runners. For more information, see [Tutorial: Configure a CodeBuild-hosted GitHub Actions runner](action-runner.md). 1. Continue with the default values and then choose **Create build project**. # Filter GitHub organization webhook events (CloudFormation) To use an CloudFormation template to filter organization webhook events, use the AWS CodeBuild project's `ScopeConfiguration` property. For more information about global and organization GitHub webhooks, see [GitHub global and organization webhooks](github-global-organization-webhook.md). **Note** Global webhooks and GitHub Enterprise webhooks are not supported by CloudFormation. The following YAML-formatted portion of an CloudFormation template creates four filter groups. Together, they trigger a build when one or all evaluate to true: + The first filter group specifies pull requests are created or updated on branches with Git reference names that match the regular expression `^refs/heads/main$` by a GitHub user who does not have account ID `12345`. + The second filter group specifies push requests are created on files with names that match the regular expression `READ_ME` in branches with Git reference names that match the regular expression `^refs/heads/.*`. + The third filter group specifies a push request with a head commit message matching the regular expression `\[CodeBuild\]`. + The fourth filter group specifies a GitHub Actions workflow job request with a workflow name matching the regular expression `\[CI-CodeBuild\]`. ``` CodeBuildProject: Type: AWS::CodeBuild::Project Properties: Name: MyProject ServiceRole: service-role Artifacts: Type: NO_ARTIFACTS Environment: Type: LINUX_CONTAINER ComputeType: BUILD_GENERAL1_SMALL Image: aws/codebuild/standard:5.0 Source: Type: GITHUB Location: source-location Triggers: Webhook: true ScopeConfiguration: Name: organization-name Scope: GITHUB_ORGANIZATION FilterGroups: - - Type: EVENT Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED - Type: BASE_REF Pattern: ^refs/heads/main$ ExcludeMatchedPattern: false - Type: ACTOR_ACCOUNT_ID Pattern: 12345 ExcludeMatchedPattern: true - - Type: EVENT Pattern: PUSH - Type: HEAD_REF Pattern: ^refs/heads/.* - Type: FILE_PATH Pattern: READ_ME ExcludeMatchedPattern: true - - Type: EVENT Pattern: PUSH - Type: COMMIT_MESSAGE Pattern: \[CodeBuild\] - Type: FILE_PATH Pattern: ^src/.+|^test/.+ - - Type: EVENT Pattern: WORKFLOW_JOB_QUEUED - Type: WORKFLOW_NAME Pattern: \[CI-CodeBuild\] ``` # GitHub manual webhooks You can configure manual GitHub webhooks to prevent CodeBuild from automatically attempting to create a webhook within GitHub. CodeBuild returns a payload URL in as part of the call to create the webhook and can be used to manually create the webhook within GitHub. Even if CodeBuild is not allowlisted to create a webhook in your GitHub account, you can still manually create a webhook for your build project. Use the following procedure to create a GitHub manual webhook. **To create a GitHub manual webhook** 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. Create a build project. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md). + In **Source**: + For **Source provider**, choose **GitHub**. + For **Repository**, choose **Repository in my GitHub account**. + For **Repository URL**, enter **https://github.com/*user-name*/*repository-name***. + In **Primary source webhook events**: + For **Webhook - optional**, choose **Rebuild every time a code change is pushed to this repository**. + Choose **Additional configuration** and for **Manual creation - optional**, choose **Manually create a webhook for this repository in GitHub console.**. 1. Continue with the default values and then choose **Create build project**. Take note of the **Payload URL** and **Secret** values as you will use these later. ![\[Payload URL and Secret configuration for manual webhooks.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-manual-webhook-values.png) 1. Open the GitHub console at `https://github.com/user-name/repository-name/settings/hooks` and choose **Add webhook**. + For **Payload URL**, enter the Payload URL value you took note of earlier. + For **Content type**, choose **application/json**. + For **Secret**, enter the Secret value you took note of earlier. + Configure the individual events that will send a webhook payload to CodeBuild. For **Which events would you like to trigger this webhook?**, choose **Let me select individual events**, and then choose from the following events: **Pushes**, **Pull requests**, and **Releases**. If you want to start builds for `WORKFLOW_JOB_QUEUED` events, choose **Workflow jobs**. To learn more about GitHub Actions runners, see [Tutorial: Configure a CodeBuild-hosted GitHub Actions runner](action-runner.md). To learn more about event types supported by CodeBuild, see [GitHub webhook events](github-webhook.md). 1. Choose **Add webhook**. # GitHub webhook events You can use webhook filter groups to specify which GitHub webhook events trigger a build. For example, you can specify that a build is only triggered for changes to specific branches. You can create one or more webhook filter groups to specify which webhook events trigger a build. A build is triggered if any filter group evaluates to true, which occurs when all the filters in the group evaluate to true. When you create a filter group, you specify: **An event** For GitHub, you can choose one or more of the following events: `PUSH`, `PULL_REQUEST_CREATED`, `PULL_REQUEST_UPDATED`, `PULL_REQUEST_REOPENED`, `PULL_REQUEST_MERGED`, `PULL_REQUEST_CLOSED`, `RELEASED`, `PRERELEASED`, and `WORKFLOW_JOB_QUEUED`. The webhook event type is in the `X-GitHub-Event` header in the webhook payload. In the `X-GitHub-Event` header, you might see `pull_request` or `push`. For a pull request event, the type is in the `action` field of the webhook event payload. The following table shows how `X-GitHub-Event` header values and webhook pull request payload `action` field values map to the available event types. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/github-webhook.html) The `PULL_REQUEST_REOPENED` event type can be used with GitHub and GitHub Enterprise Server only. The `RELEASED` and `PRERELEASED` event type can be used with GitHub only. For more information on `WORKFLOW_JOB_QUEUED`, see [Tutorial: Configure a CodeBuild-hosted GitHub Actions runner](action-runner.md). **One or more optional filters** Use a regular expression to specify a filter. For an event to trigger a build, every filter within the group associated with it must evaluate to true. `ACTOR_ACCOUNT_ID` (`ACTOR_ID` in the console) A webhook event triggers a build when a GitHub or GitHub Enterprise Server account ID matches the regular expression pattern. This value is found in the `id` property of the `sender` object in the webhook payload. `HEAD_REF` A webhook event triggers a build when the head reference matches the regular expression pattern (for example, `refs/heads/branch-name` or `refs/tags/tag-name`). For a push event, the reference name is found in the `ref` property in the webhook payload. For pull requests events, the branch name is found in the `ref` property of the `head` object in the webhook payload. `BASE_REF` A webhook event triggers a build when the base reference matches the regular expression pattern (for example, `refs/heads/branch-name`). A `BASE_REF` filter can be used with pull request events only. The branch name is found in the `ref` property of the `base` object in the webhook payload. `FILE_PATH` A webhook triggers a build when the path of a changed file matches the regular expressions pattern. A `FILE_PATH` filter can be used with GitHub push and pull request events and GitHub Enterprise Server push events. It cannot be used with GitHub Enterprise Server pull request events. `COMMIT_MESSAGE` A webhook triggers a build when the head commit message matches the regular expression pattern. A `COMMIT_MESSAGE` filter can be used with GitHub push and pull request events and GitHub Enterprise Server push events. It cannot be used with GitHub Enterprise Server pull request events. `TAG_NAME` A webhook triggers a build when the tag name of the release matches the regular expression pattern. A `TAG_NAME` filter can be used with GitHub released and prereleased request events. `RELEASE_NAME` A webhook triggers a build when the release name matches the regular expression pattern. A `RELEASE_NAME` filter can be used with GitHub released and prereleased request events. `REPOSITORY_NAME` A webhook triggers a build when the repository name matches the regular expression pattern. A `REPOSITORY_NAME` filter can only be used with GitHub global or organization webhooks. `ORGANIZATION_NAME` A webhook triggers a build when the organization name matches the regular expression pattern. A `ORGANIZATION_NAME` filter can only be used with GitHub global webhooks. `WORKFLOW_NAME` A webhook triggers a build when the workflow name matches the regular expression pattern. A `WORKFLOW_NAME` filter can be used with GitHub Actions workflow job queued request events. **Note** You can find the webhook payload in the webhook settings of your GitHub repository. **Topics** + [Filter GitHub webhook events (console)](github-webhook-events-console.md) + [Filter GitHub webhook events (SDK)](github-webhook-events-sdk.md) + [Filter GitHub webhook events (CloudFormation)](github-webhook-events-cfn.md) # Filter GitHub webhook events (console) Use the following instructions to filter GitHub webhook events using the AWS Management Console. For more information about GitHub webhook events, see [GitHub webhook events](github-webhook.md). In **Primary source webhook events**, select the following. This section is only available when you chose **Repository in my GitHub account** for the source repository. 1. Select **Rebuild every time a code change is pushed to this repository** when you create your project. 1. From **Event type**, choose one or more events. 1. To filter when an event triggers a build, under **Start a build under these conditions**, add one or more optional filters. 1. To filter when an event is not triggered, under **Don't start a build under these conditions**, add one or more optional filters. 1. Choose **Add filter group** to add another filter group, if needed. For more information, see [Create a build project (console)](create-project.md#create-project-console) and [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *AWS CodeBuild API Reference*. In this example, a webhook filter group triggers a build for pull requests only: ![\[A webhook filter group that triggers a build for pull requests only.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter.png) Using an example of two webhook filter groups, a build is triggered when one or both evaluate to true: + The first filter group specifies pull requests that are created, updated, or reopened on branches with Git reference names that match the regular expression `^refs/heads/main$` and head references that match `^refs/heads/branch1$`. + The second filter group specifies push requests on branches with Git reference names that match the regular expression `^refs/heads/branch1$`. ![\[An example of two filter groups.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-head-base-regexes.png) In this example, a webhook filter group triggers a build for all requests except tag events. ![\[A webhook filter group that triggers a build for all requests except tag events.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-exclude.png) In this example, a webhook filter group triggers a build only when files with names that match the regular expression `^buildspec.*` change. ![\[A webhook filter group that triggers a build only when files with names that match the regular expression specified.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-regex.png) In this example, a webhook filter group triggers a build only when files are changed in `src` or `test` folders. ![\[A webhook filter group that triggers a build only when files are changed in specified folders.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-combined-regex.png) In this example, a webhook filter group triggers a build only when a change is made by a specified GitHub or GitHub Enterprise Server user with an account ID that matches the regular expression `actor-account-id`. **Note** For information about how to find your GitHub account ID, see https://api.github.com/users/*user-name*, where *user-name* is your GitHub user name. ![\[A webhook filter group that triggers a build only when a change is made by a specified GitHub user with an account ID that matches the regular expression.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-actor.png) In this example, a webhook filter group triggers a build for a push event when the head commit message matches the regular expression `\[CodeBuild\]`. ![\[A webhook filter group that triggers a build for a push event when the head commit message matches the regular expression.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-commit-message.png) In this example, a webhook filter group triggers a build for GitHub Actions workflow job events only. **Note** CodeBuild will only process GitHub Actions workflow jobs if a webhook has filter groups containing the **WORKFLOW\$1JOB\$1QUEUED** event filter. ![\[A webhook filter group triggers a build for GitHub Actions workflow job events only.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-actions-workflow-job-queued-no-highlight.png) In this example, a webhook filter group triggers a build for a workflow name that matches the regular expression `CI-CodeBuild`. ![\[A webhook filter group triggers a build for a workflow name that matches the regular expression.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-actions-workflow-job-specific.png) # Filter GitHub webhook events (SDK) To use the AWS CodeBuild SDK to filter webhook events, use the `filterGroups` field in the request syntax of the `CreateWebhook` or `UpdateWebhook` API methods. For more information, see [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *CodeBuild API Reference*. For more information about GitHub webhook events, see [GitHub webhook events](github-webhook.md). To create a webhook filter that triggers a build for pull requests only, insert the following into the request syntax: ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED, PULL_REQUEST_CLOSED" } ] ] ``` To create a webhook filter that triggers a build for specified branches only, use the `pattern` parameter to specify a regular expression to filter branch names. Using an example of two filter groups, a build is triggered when one or both evaluate to true: + The first filter group specifies pull requests that are created, updated, or reopened on branches with Git reference names that match the regular expression `^refs/heads/main$` and head references that match `^refs/heads/myBranch$`. + The second filter group specifies push requests on branches with Git reference names that match the regular expression `^refs/heads/myBranch$`. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED" }, { "type": "HEAD_REF", "pattern": "^refs/heads/myBranch$" }, { "type": "BASE_REF", "pattern": "^refs/heads/main$" } ], [ { "type": "EVENT", "pattern": "PUSH" }, { "type": "HEAD_REF", "pattern": "^refs/heads/myBranch$" } ] ] ``` You can use the `excludeMatchedPattern` parameter to specify which events do not trigger a build. For example, in this example a build is triggered for all requests except tag events. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED, PULL_REQUEST_CLOSED" }, { "type": "HEAD_REF", "pattern": "^refs/tags/.*", "excludeMatchedPattern": true } ] ] ``` You can create a filter that triggers a build only when files with names that match the regular expression in the `pattern` argument change. In this example, the filter group specifies that a build is triggered only when files with a name that matches the regular expression `^buildspec.*` change. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH" }, { "type": "FILE_PATH", "pattern": "^buildspec.*" } ] ] ``` In this example, the filter group specifies that a build is triggered only when files are changed in `src` or `test` folders. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH" }, { "type": "FILE_PATH", "pattern": "^src/.+|^test/.+" } ] ] ``` You can create a filter that triggers a build only when a change is made by a specified GitHub or GitHub Enterprise Server user with account ID `actor-account-id`. **Note** For information about how to find your GitHub account ID, see https://api.github.com/users/*user-name*, where *user-name* is your GitHub user name. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED, PULL_REQUEST_CLOSED" }, { "type": "ACTOR_ACCOUNT_ID", "pattern": "actor-account-id" } ] ] ``` You can create a filter that triggers a build only when the head commit message matches the regular expression in the pattern argument. In this example, the filter group specifies that a build is triggered only when the head commit message of the push event matches the regular expression `\[CodeBuild\]`. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH" }, { "type": "COMMIT_MESSAGE", "pattern": "\[CodeBuild\]" } ] ] ``` To create a webhook filter that triggers a build for GitHub Actions workflow jobs only, insert the following into the request syntax: ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "WORKFLOW_JOB_QUEUED" } ] ] ``` # Filter GitHub webhook events (CloudFormation) To use an CloudFormation template to filter webhook events, use the AWS CodeBuild project's `FilterGroups` property. For more information about GitHub webhook events, see [GitHub webhook events](github-webhook.md). The following YAML-formatted portion of an CloudFormation template creates two filter groups. Together, they trigger a build when one or both evaluate to true: + The first filter group specifies pull requests are created or updated on branches with Git reference names that match the regular expression `^refs/heads/main$` by a GitHub user who does not have account ID `12345`. + The second filter group specifies push requests are created on files with names that match the regular expression `READ_ME` in branches with Git reference names that match the regular expression `^refs/heads/.*`. + The third filter group specifies a push request with a head commit message matching the regular expression `\[CodeBuild\]`. + The fourth filter group specifies a GitHub Actions workflow job request with a workflow name matching the regular expression `\[CI-CodeBuild\]`. ``` CodeBuildProject: Type: AWS::CodeBuild::Project Properties: Name: MyProject ServiceRole: service-role Artifacts: Type: NO_ARTIFACTS Environment: Type: LINUX_CONTAINER ComputeType: BUILD_GENERAL1_SMALL Image: aws/codebuild/standard:5.0 Source: Type: GITHUB Location: source-location Triggers: Webhook: true FilterGroups: - - Type: EVENT Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED - Type: BASE_REF Pattern: ^refs/heads/main$ ExcludeMatchedPattern: false - Type: ACTOR_ACCOUNT_ID Pattern: 12345 ExcludeMatchedPattern: true - - Type: EVENT Pattern: PUSH - Type: HEAD_REF Pattern: ^refs/heads/.* - Type: FILE_PATH Pattern: READ_ME ExcludeMatchedPattern: true - - Type: EVENT Pattern: PUSH - Type: COMMIT_MESSAGE Pattern: \[CodeBuild\] - Type: FILE_PATH Pattern: ^src/.+|^test/.+ - - Type: EVENT Pattern: WORKFLOW_JOB_QUEUED - Type: WORKFLOW_NAME Pattern: \[CI-CodeBuild\] ``` # GitLab group webhooks You can use CodeBuild GitLab group webhooks to start builds on webhook events from any repository within a GitLab group. Group webhooks work with any of the existing GitLab webhook event types, and can be configured by adding a scope configuration when creating a CodeBuild webhook. You can also use group webhooks to [set up self-hosted GitLab runners within CodeBuild](gitlab-runner.md) in order to receive `WORKFLOW_JOB_QUEUED` events from multiple repositories within a single project. **Topics** + [Set up a group GitLab webhook](gitlab-group-webhook-setup.md) + [Filter GitLab group webhook events (console)](gitlab-group-webhook-events-console.md) + [Filter GitLab group webhook events (CloudFormation)](gitlab-group-webhook-events-cfn.md) # Set up a group GitLab webhook The high-level steps to set up a group GitLab webhook are as follows. For more information about group GitLab webhooks, see [GitLab group webhooks](gitlab-group-webhook.md). 1. Set your project's source location to `CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION`. 1. In the webhook's scope configuration, set the scope to `GITLAB_GROUP`. 1. Specify a name as part of the webhook's scope configuration. For group webhooks, this is the group name. **Note** If the project's source type is `GITLAB_SELF_MANAGED`, you will also need to specify a domain as part of the webhook scope configuration. 1. (Optional) If you would only like to receive webhook events for specific repositories within your organization or enterprise, you can specify `REPOSITORY_NAME` as a filter when creating the webhook. 1. When creating a group webhook, ensure that CodeBuild has permissions to create group level webhooks within GitLab. To do so, you can use CodeBuild OAuth though CodeConnections. For more information, see [GitLab access in CodeBuild](access-tokens-gitlab-overview.md). Note that group webhooks work with any of the existing GitLab webhook event types. # Filter GitLab group webhook events (console) When creating a GitLab project through the console, select the following options to create a GitLab group webhook within the project. For more information about group GitLab webhooks, see [GitLab group webhooks](gitlab-group-webhook.md). 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. Create a build project. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md). + In **Source**: + For **Source provider**, choose **GitLab** or **GitLab Self Managed**. + For **Repository**, choose **GitLab scoped webhook**. The GitLab repository will automatically be set to `CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION`, which is the required source location for group webhooks. **Note** When using group webhooks, make sure that CodeBuild has permissions to create group level webhooks within GitLab. If you're using an [existing OAuth connection](access-tokens-gitlab-overview.md#connections-gitlab), you may need to regenerate the connection in order to grant CodeBuild this permission. ![\[The configuration of GitLab scoped webhook.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/gitlab-group-source.png) + In **Primary source webhook events**: + For **Group name**, enter the group name. If the project's source type is `GITLAB_SELF_MANAGED`, you also need to specify a domain as part of the webhook group configuration. For example, if the URL of your group is **https://domain.com/group/group-name**, then the domain is **https://domain.com**. **Note** This name cannot be changed after the webhook has been created. To change the name, you can delete and re-create the webhook. If you want to remove the webhook entirely, you can also update the project source location to a GitLab repository. ![\[The configuration of group webhooks.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/gitlab-group-webhook-primary-events.png) + (Optional) In **Webhook event filter groups**, you can specify which [events you would like to trigger a new build](gitlab-webhook.md). You can also specify `REPOSITORY_NAME` as a filter to only trigger builds on webhook events from specific repositories. ![\[A filter that only triggers builds on webhook events from specific repositories.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-organization-webhook-filter-groups.png) You can also set the event type to `WORKFLOW_JOB_QUEUED` to set up self-hosted GitLab runners. For more information, see [Self-managed GitLab runners in AWS CodeBuild](gitlab-runner.md). 1. Continue with the default values and then choose **Create build project**. # Filter GitLab group webhook events (CloudFormation) To use an CloudFormation template to filter group webhook events, use the AWS CodeBuild project's `ScopeConfiguration` property. For more information about group GitLab webhooks, see [GitLab group webhooks](gitlab-group-webhook.md). The following YAML-formatted portion of an CloudFormation template creates four filter groups. Together, they trigger a build when one or all evaluate to true: + The first filter group specifies pull requests are created or updated on branches with Git reference names that match the regular expression `^refs/heads/main$` by a GitLab user who does not have account ID `12345`. + The second filter group specifies push requests are created on files with names that match the regular expression `READ_ME` in branches with Git reference names that match the regular expression `^refs/heads/.*`. + The third filter group specifies a push request with a head commit message matching the regular expression `\[CodeBuild\]`. + The fourth filter group specifies a GitLab CI/CD pipeline job request with a CI/CD pipeline name matching the regular expression `\[CI-CodeBuild\]`. ``` CodeBuildProject: Type: AWS::CodeBuild::Project Properties: Name: MyProject ServiceRole: service-role Artifacts: Type: NO_ARTIFACTS Environment: Type: LINUX_CONTAINER ComputeType: BUILD_GENERAL1_SMALL Image: aws/codebuild/standard:5.0 Source: Type: GITLAB Location: source-location Triggers: Webhook: true ScopeConfiguration: Name: group-name Scope: GITLAB_GROUP FilterGroups: - - Type: EVENT Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED - Type: BASE_REF Pattern: ^refs/heads/main$ ExcludeMatchedPattern: false - Type: ACTOR_ACCOUNT_ID Pattern: 12345 ExcludeMatchedPattern: true - - Type: EVENT Pattern: PUSH - Type: HEAD_REF Pattern: ^refs/heads/.* - Type: FILE_PATH Pattern: READ_ME ExcludeMatchedPattern: true - - Type: EVENT Pattern: PUSH - Type: COMMIT_MESSAGE Pattern: \[CodeBuild\] - Type: FILE_PATH Pattern: ^src/.+|^test/.+ - - Type: EVENT Pattern: WORKFLOW_JOB_QUEUED - Type: WORKFLOW_NAME Pattern: \[CI-CodeBuild\] ``` # GitLab manual webhooks You can configure manual GitLab webhooks to prevent CodeBuild from automatically attempting to create a webhook within GitLab. CodeBuild returns a payload URL in as part of the call to create the webhook and can be used to manually create the webhook within GitLab. Even if CodeBuild is not allowlisted to create a webhook in your GitLab account, you can still manually create a webhook for your build project. Use the following procedure to create a GitLab manual webhook. **To create a GitLab manual webhook** 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. Create a build project. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md). + In **Source**: + For **Source provider**, choose **GitLab**. + For **Repository**, choose **Repository in my GitLab account**. + For **Repository URL**, enter **https://gitlab.com/*user-name*/*repository-name***. + In **Primary source webhook events**: + For **Webhook - optional**, choose **Rebuild every time a code change is pushed to this repository**. + Choose **Additional configuration** and for **Manual creation - optional**, choose **Manually create a webhook for this repository in GitLab console.**. 1. Continue with the default values and then choose **Create build project**. Take note of the **Payload URL** and **Secret** values as you will use these later. 1. Open the GitLab console at `https://gitlab.com/user-name/repository-name/-/hooks` and choose **Add new webhook**. + For **URL**, enter the Payload URL value you took note of earlier. + For **Secret token**, enter the Secret value you took note of earlier. + Configure the individual events that will send a webhook payload to CodeBuild. For **Trigger**, choose from the following events: **Push events**, **Merge request events**, **Releases events**, and **Job events**. To learn more about event types supported by CodeBuild, see [GitLab webhook events](gitlab-webhook.md). 1. Choose **Add webhook**. # GitLab webhook events You can use webhook filter groups to specify which GitLab webhook events trigger a build. For example, you can specify that a build is only triggered for changes to specific branches. You can create one or more webhook filter groups to specify which webhook events trigger a build. A build is triggered if any filter group evaluates to true, which occurs when all the filters in the group evaluate to true. When you create a filter group, you specify: **An event** For GitLab, you can choose one or more of the following events: `PUSH`, `PULL_REQUEST_CREATED`, `PULL_REQUEST_UPDATED`, `PULL_REQUEST_MERGED`, `PULL_REQUEST_REOPENED`, `PULL_REQUEST_CLOSED`, `RELEASED`, and `WORKFLOW_JOB_QUEUED`. The webhook's event type is in its header in the `X-GitLab-Event` field. The following table shows how `X-GitLab-Event` header values map to the event types. For the `Merge Request Hook` webhook event, the payload's `object_atttributes.action` will contain additional information on merge request type. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/gitlab-webhook.html) For `PULL_REQUEST_MERGED`, if a pull request is merged with the squash strategy and the pull request branch is closed, the original pull request commit no longer exists. In this case, the `CODEBUILD_WEBHOOK_MERGE_COMMIT` environment variable contains the identifier of the squashed merge commit. **One or more optional filters** Use a regular expression to specify a filter. For an event to trigger a build, every filter within the group associated with it must evaluate to true. `ACTOR_ACCOUNT_ID` (`ACTOR_ID` in the console) A webhook event triggers a build when a GitLab account ID matches the regular expression pattern. This value appears in the `account_id` property of the `actor` object in the webhook filter payload. `HEAD_REF` A webhook event triggers a build when the head reference matches the regular expression pattern (for example, `refs/heads/branch-name` and `refs/tags/tag-name`). A `HEAD_REF` filter evaluates the Git reference name for the branch or tag. The branch or tag name appears in the `name` field of the `new` object in the `push` object of the webhook payload. For pull request events, the branch name appears in the `name` field in the `branch` object of the `source` object in the webhook payload. `BASE_REF` A webhook event triggers a build when the base reference matches the regular expression pattern. A `BASE_REF` filter works with pull request events only (for example, `refs/heads/branch-name`). A `BASE_REF` filter evaluates the Git reference name for the branch. The branch name appears in the `name` field of the `branch` object in the `destination` object in the webhook payload. `FILE_PATH` A webhook triggers a build when the path of a changed file matches the regular expression pattern. `COMMIT_MESSAGE` A webhook triggers a build when the head commit message matches the regular expression pattern. `WORKFLOW_NAME` A webhook triggers a build when the workflow name matches the regular expression pattern. **Note** You can find the webhook payload in the webhook settings of your GitLab repository. **Topics** + [Filter GitLab webhook events (console)](gitlab-webhook-events-console.md) + [Filter GitLab webhook events (SDK)](gitlab-webhook-events-sdk.md) + [Filter GitLab webhook events (CloudFormation)](gitlab-webhook-events-cfn.md) # Filter GitLab webhook events (console) Use the following instructions to use the AWS Management Console to filter webhook events. For more information about GitLab webhook events, see [GitLab webhook events](gitlab-webhook.md). 1. Select **Rebuild every time a code change is pushed to this repository** when you create your project. 1. From **Event type**, choose one or more events. 1. To filter when an event triggers a build, under **Start a build under these conditions**, add one or more optional filters. 1. To filter when an event is not triggered, under **Don't start a build under these conditions**, add one or more optional filters. 1. Choose **Add filter group** to add another filter group. For more information, see [Create a build project (console)](create-project.md#create-project-console) and [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *AWS CodeBuild API Reference*. In this example, a webhook filter group triggers a build for pull requests only: ![\[A webhook filter group that triggers a build for pull requests only.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-gitlab.png) Using an example of two filter groups, a build is triggered when one or both evaluate to true: + The first filter group specifies pull requests that are created or updated on branches with Git reference names that match the regular expression `^refs/heads/main$` and head references that match `^refs/heads/branch1!`. + The second filter group specifies push requests on branches with Git reference names that match the regular expression `^refs/heads/branch1$`. ![\[An example of two filter groups.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-head-base-regexes-gitlab.png) In this example, a webhook filter group triggers a build for all requests except tag events. ![\[A webhook filter group that triggers a build for all requests except tag events.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-exclude-gitlab.png) In this example, a webhook filter group triggers a build only when files with names that match the regular expression `^buildspec.*` change. ![\[A webhook filter group that triggers a build only when files with names that match the regular expression specified.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-regex-gitlab.png) In this example, a webhook filter group triggers a build only when files are changed in `src` or `test` folders. ![\[A webhook filter group that triggers a build only when files are changed in specified folders.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-combined-regex-gitlab.png) In this example, a webhook filter group triggers a build only when a change is made by a GitLab user who does not have an account ID that matches the regular expression `actor-account-id`. **Note** For information about how to find your GitLab account ID, see https://api.github.com/users/*user-name*, where *user-name* is your GitLab user name. ![\[A webhook filter group that triggers a build only when a change is made by a GitLab user who does not have an account ID.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-actor-gitlab.png) In this example, a webhook filter group triggers a build for a push event when the head commit message matches the regular expression `\[CodeBuild\]`. ![\[A webhook filter group that triggers a build for a push event when the head commit message matches the regular expression.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-commit-message-gitlab.png) # Filter GitLab webhook events (SDK) To use the AWS CodeBuild SDK to filter webhook events, use the `filterGroups` field in the request syntax of the `CreateWebhook` or `UpdateWebhook` API methods. For more information, see [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *CodeBuild API Reference*. For more information about GitLab webhook events, see [GitLab webhook events](gitlab-webhook.md). To create a webhook filter that triggers a build for pull requests only, insert the following into the request syntax: ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED" } ] ] ``` To create a webhook filter that triggers a build for specified branches only, use the `pattern` parameter to specify a regular expression to filter branch names. Using an example of two filter groups, a build is triggered when one or both evaluate to true: + The first filter group specifies pull requests that are created or updated on branches with Git reference names that match the regular expression `^refs/heads/main$` and head references that match `^refs/heads/myBranch$`. + The second filter group specifies push requests on branches with Git reference names that match the regular expression `^refs/heads/myBranch$`. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED" }, { "type": "HEAD_REF", "pattern": "^refs/heads/myBranch$" }, { "type": "BASE_REF", "pattern": "^refs/heads/main$" } ], [ { "type": "EVENT", "pattern": "PUSH" }, { "type": "HEAD_REF", "pattern": "^refs/heads/myBranch$" } ] ] ``` You can use the `excludeMatchedPattern` parameter to specify which events do not trigger a build. In this example, a build is triggered for all requests except tag events. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED" }, { "type": "HEAD_REF", "pattern": "^refs/tags/.*", "excludeMatchedPattern": true } ] ] ``` You can create a filter that triggers a build only when a change is made by a GitLab user with account ID `actor-account-id`. **Note** For information about how to find your GitLab account ID, see https://api.github.com/users/*user-name*, where *user-name* is your GitLab user name. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED" }, { "type": "ACTOR_ACCOUNT_ID", "pattern": "actor-account-id" } ] ] ``` You can create a filter that triggers a build only when files with names that match the regular expression in the `pattern` argument change. In this example, the filter group specifies that a build is triggered only when files with a name that matches the regular expression `^buildspec.*` change. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH" }, { "type": "FILE_PATH", "pattern": "^buildspec.*" } ] ] ``` In this example, the filter group specifies that a build is triggered only when files are changed in `src` or `test` folders. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH" }, { "type": "FILE_PATH", "pattern": "^src/.+|^test/.+" } ] ] ``` You can create a filter that triggers a build only when the head commit message matches the regular expression in the pattern argument. In this example, the filter group specifies that a build is triggered only when the head commit message of the push event matches the regular expression `\[CodeBuild\]`. ``` "filterGroups": [ [ { "type": "EVENT", "pattern": "PUSH" }, { "type": "COMMIT_MESSAGE", "pattern": "\[CodeBuild\]" } ] ] ``` # Filter GitLab webhook events (CloudFormation) To use an CloudFormation template to filter webhook events, use the AWS CodeBuild project's `FilterGroups` property. For more information about GitLab webhook events, see [GitLab webhook events](gitlab-webhook.md). The following YAML-formatted portion of an CloudFormation template creates two filter groups. Together, they trigger a build when one or both evaluate to true: + The first filter group specifies pull requests are created or updated on branches with Git reference names that match the regular expression `^refs/heads/main$` by a GitLab user who does not have account ID `12345`. + The second filter group specifies push requests are created on branches with Git reference names that match the regular expression `^refs/heads/.*`. + The third filter group specifies a push request with a head commit message matching the regular expression `\[CodeBuild\]`. + The fourth filter group specifies a GitHub Actions workflow job request with a workflow name matching the regular expression `\[CI-CodeBuild\]`. ``` CodeBuildProject: Type: AWS::CodeBuild::Project Properties: Name: MyProject ServiceRole: service-role Artifacts: Type: NO_ARTIFACTS Environment: Type: LINUX_CONTAINER ComputeType: BUILD_GENERAL1_SMALL Image: aws/codebuild/standard:5.0 Source: Type: GITLAB Location: source-location Triggers: Webhook: true FilterGroups: - - Type: EVENT Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED - Type: BASE_REF Pattern: ^refs/heads/main$ ExcludeMatchedPattern: false - Type: ACTOR_ACCOUNT_ID Pattern: 12345 ExcludeMatchedPattern: true - - Type: EVENT Pattern: PUSH - Type: HEAD_REF Pattern: ^refs/heads/.* - - Type: EVENT Pattern: PUSH - Type: COMMIT_MESSAGE Pattern: \[CodeBuild\] - - Type: EVENT Pattern: WORKFLOW_JOB_QUEUED - Type: WORKFLOW_NAME Pattern: \[CI-CodeBuild\] ``` # Buildkite manual webhooks Currently, CodeBuild requires all Buildkite webhooks to be created manually. CodeBuild returns a payload URL as part of the call to create the webhook, which can be used to manually create the webhook within Buildkite. Use the following procedure to create a Buildkite manual webhook. **To create a CodeBuild project with a webhook** 1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home). 1. Create a build project. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md). 1. In **Project configuration**, choose **Runner project**. In **Runner**: + For **Runner provider**, choose **Buildkite**. + For **Buildkite agent token**, choose **Create a new agent token by using the create secret page**. You will be prompted to create a new secret in AWS Secrets Manager with a secret value equal to the Buildkite agent token you generated above. + (Optional) If you would like to use CodeBuild managed credentials for your job, select your job’s source repository provider under **Buildkite source credential options** and verify that credentials are configured for your account. Additionally, verify that your Buildkite pipeline uses **Checkout using HTTPS**. 1. + In **Environment**: + Choose a supported **Environment image** and **Compute**. Note that you have the option to override the image and instance settings by using a label in your GitHub Actions workflow YAML. For more information, see [Step 2: Update your GitHub Actions workflow YAML](action-runner.md#sample-github-action-runners-update-yaml) + In **Buildspec**: + Note that your buildspec will be ignored unless `buildspec-override:true` is added as a label. Instead, CodeBuild will override it to use commands that will setup the self-hosted runner. 1. Continue with the default values and then choose **Create build project**. 1. Save the **Payload URL** and **Secret** values from the **Create Webhook** popup. Follow the instructions in the popup to create a new Buildkite organization webhook. # Pull request comment approval CodeBuild supports pull request build policies that provide additional control over builds triggered by pull requests. You may not want to automatically build pull requests from unknown users until their changes can be reviewed. This feature allows you to require one of your team members to first review the code and then run the pipeline. This is commonly used as a security measure when building a code submitted by unknown contributors. Pull request build policies allow you to control when CodeBuild triggers builds for pull requests based on the contributor's permissions and approval status. This is particularly important for public repositories or repositories that accept contributions from external collaborators. When enabled, this feature ensures that builds are only triggered for pull requests when either: + The pull request is created by a trusted contributor. + A trusted contributor approves the pull request by posting a specific comment. ## How it works **Trusted contributors** Trusted contributor is a user who’s current role in the source control system is set in the pull request based policy as an approver roles. When a trusted contributor creates a pull request, CodeBuild triggers the build automatically, maintaining the current behavior. **Untrusted contributors** Untrusted contributor is a user who’s role is not set in the list of the approver roles. When an untrusted contribute creates a pull request: 1. CodeBuild marks the build status as “Failed" with the message "Pull request approval required for starting a build". 1. A trusted contributor must review the changes and post a comment with `/codebuild_run()` to trigger the build. For example, `/codebuild_run(046e8b67481d53bdc86c3f6affdd5d1afae6d369)`. 1. CodeBuild validates the commenter's permissions and triggers the build if approved. 1. Build results are reported back on the pull request page. **Comment approval syntax** Trusted contributors can approve builds using the following comment formats: + `/codebuild_run(046e8b67481d53bdc86c3f6affdd5d1afae6d369)` - Triggers build on the specified commit SHA. ## Configuration **Default behavior** Pull request build policy is enabled by default for all newly created CodeBuild projects. **API parameters** The pull request build policy is configured using the `PullRequestBuildPolicy` parameter in the following actions: + `CreateWebhook` + `UpdateWebhook` **`PullRequestBuildPolicy` structure** ``` { "requiresCommentApproval": "string", "approverRoles": ["string", ...] } ``` **`requiresCommentApproval`** Specifies when comment-based approval is required before triggering a build on pull requests. This setting determines whether builds run automatically or require explicit approval through comments. Type: String Valid values: + `DISABLED` - Builds trigger automatically without requiring comment approval. + `FORK_PULL_REQUESTS` - Only pull requests from forked repositories require comment approval (unless contributor is one of the approver roles). + `ALL_PULL_REQUESTS` - All pull requests require comment approval before builds execute (unless contributor is one of the approver roles). This is the default value. **`approverRoles`** List of repository roles that have approval privileges for pull request builds when comment approval is required. Only users with these roles can provide valid comment approvals. If a pull request contributor is one of these roles, their pull request builds will trigger automatically. Type: Array of strings Valid values for GitHub projects (the values are mapped to the GitHub roles): + `GITHUB_ADMIN` - Repository administrators + `GITHUB_MAINTAIN` - Repository maintainers + `GITHUB_WRITE` - User with write permissions + `GITHUB_TRIAGE` - User with triage permissions + `GITHUB_READ` - User with read permissions + Default: `["GITHUB_ADMIN", "GITHUB_MAINTAINER", "GITHUB_WRITE"]` Valid values for GitLab projects (the values are mapped to the GitLab roles): + `GITLAB_OWNER` - Repository owner + `GITLAB_MAINTAINER` - Repository maintainer + `GITLAB_DEVELOPER` - User with developer permissions + `GITLAB_REPORTER` - User with reporter permissions + `GITLAB_PLANNER` - User with planner permissions + `GITLAB_GUEST ` - User with guest permissions + Default: `["GITLAB_OWNER", "GITLAB_MAINTAINER", "GITLAB_DEVELOPER"]` Valid values for Bitbucket projects (the values are mapped to the Bitbucket roles): + `BITBUCKET_ADMIN ` - Repository administrator + `BITBUCKET_WRITE` - User with write permissions + `BITBUCKET_READ ` - User with read permissions + Default: `["BITBUCKET_ADMIN", "BITBUCKET_WRITE"]` ## Examples **Enable comment approval for all pull requests** To use the AWS CodeBuild SDK to enable or disable Pull Request Build policy for a webhook, use the `pullRequestBuildPolicy` field in the request syntax of the `CreateWebhook` or `UpdateWebhook` API methods. For more information, see [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *CodeBuild API Reference*. Users with Github roles Admin, Maintain, and Write will be treated as trusted contributors. ``` "pullRequestBuildPolicy": { "requiresCommentApproval": "ALL_PULL_REQUESTS", "approverRoles": ["GITHUB_ADMIN", "GITHUB_MAINTAIN", "GITHUB_WRITE"] } ``` **Enable comment approval only for repository admins and maintainers** Users with GitHub roles Admin, Maintain, will be treated as trusted contributors. ``` "pullRequestBuildPolicy": { "requiresCommentApproval": "FORK_PULL_REQUESTS", "approverRoles": ["GITHUB_ADMIN", "GITHUB_MAINTAINER"] } ``` **Disable comment approval** ``` "pullRequestBuildPolicy": { "requiresCommentApproval": "DISABLED" } ``` ## AWS CloudFormation To use an AWS CloudFormation template to enable or disable Pull Request Build policy for a webhook use PullRequestBuildPolicy property. The following YAML-formatted portion of an AWS CloudFormation template create a project with a webhook that has Pull Request Build Policy enabled for all pull requests. Maintain and Admin roles as specified as approvers. ``` CodeBuildProject: Type: AWS::CodeBuild::Project Properties: Name: MyProject ServiceRole: service-role Artifacts: Type: NO_ARTIFACTS Environment: Type: LINUX_CONTAINER ComputeType: BUILD_GENERAL1_SMALL Image: aws/codebuild/standard:5.0 Source: Type: BITBUCKET Location: source-location Triggers: Webhook: true FilterGroups: - - Type: EVENT Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED - Type: BASE_REF Pattern: ^refs/heads/main$ ExcludeMatchedPattern: false PullRequestBuildPolicy: RequiresCommentApproval: ALL_PULL_REQUESTS ApproverRoles: - GITHUB_MAINTAIN - GITHUB_ADMIN ``` ## Console configuration To use the AWS Management Console to filter webhook events: 1. For **Comment approval**, select either disabled or enabled for all pull requests (`ALL_PULL_REQUEST`) or only for pull requests from forks (`FORK_PULL_REQUEST`). 1. For **Approver roles**, select repository roles that have approval privileges for pull request builds when comment approval is required. For more information, see [Create a build project (console)](create-project.md#create-project-console) and [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *CodeBuild API Reference*. ![\[Primary source webhook events console with comment approval.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-comment-approval.png)