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.