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 in order to receive WORKFLOW_JOB_QUEUED events from multiple repositories within a single project.

The high-level steps to set up a global or organization GitHub webhook are as follows:

1. Set your project's source location to CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION.

2. 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. For more information, see Types of webhooks.

3. 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.

4. (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.

5. 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.

   Note that organization webhooks work with any of the existing GitHub webhook event types.

6. 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.

   Note that global webhooks only support the WORKFLOW_JOB_QUEUED event type. For more information, see Set up self-hosted GitHub Actions runners in AWS CodeBuild.

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:

1. Open the AWS CodeBuild console at https://console.aws.amazon.com/codesuite/codebuild/home.

2. Create a build project. For information, see Create a build project (console) and Run a build (console).

   • 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, 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. 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 and reconnect the token through the CodeBuild console.

     

   • 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 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.

       

     • (Optional) In Webhook event filter groups, you can specify which events you would like to trigger a new build. You can also specify REPOSITORY_NAME as a filter to only trigger builds on webhook events from specific repositories.

       

       You can also set the event type to WORKFLOW_JOB_QUEUED to set up self-hosted GitHub Actions runners. For more information, see Set up self-hosted GitHub Actions runners in AWS CodeBuild.

3. Continue with the default values and then choose Create build project.

Filter GitHub organization webhook events (AWS CloudFormation)

To use an AWS CloudFormation template to filter organization webhook events, use the AWS CodeBuild project's ScopeConfiguration property.

Note

Global webhooks and GitHub Enterprise webhooks are not supported by AWS CloudFormation.

The following YAML-formatted portion of an AWS 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
      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\]