Self-hosted GitHub Actions runners in Amazon CodeBuild - Amazon CodeBuild
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Self-hosted GitHub Actions runners in Amazon CodeBuild

You can configure your project to set up self-hosted GitHub Actions runners in CodeBuild containers to process your GitHub Actions workflow jobs. This can be done by setting up a webhook using your CodeBuild project, and updating your GitHub Actions workflow YAML to use self-hosted runners hosted on CodeBuild machines. For more information, see About self-hosted runners.

The high-level steps to configure a CodeBuild project to run GitHub Actions jobs are as follows:

  1. If you haven't done so already, create a personal access token or connect with an OAuth app to connect your project to GitHub.

  2. Navigate to the CodeBuild console and create a CodeBuild project with a webhook and set up your webhook filters.

  3. Update your GitHub Actions workflow YAML in GitHub to configure your build environment.

For a more detailed procedure, see Tutorial: Configure a CodeBuild self-hosted GitHub Actions runner.

This feature allows your GitHub Actions workflow jobs to get native integration with Amazon, which provides security and convenience through features like IAM, Amazon Secrets Manager integration, Amazon CloudTrail, and Amazon VPC. You can access latest instance types, including ARM-based instances.

Tutorial: Configure a CodeBuild self-hosted GitHub Actions runner

This tutorial shows you how to configure your CodeBuild projects to run GitHub Actions jobs.

Prerequisites

To complete this tutorial, you must first:

  • Connect with an OAuth app or create a personal access token. If you'd like to connect with an OAuth app, you must use the CodeBuild console to do so. If you'd like to create a personal access token, you can either use the CodeBuild console or use the ImportSourceCredentials API. For more instructions, see GitHub and GitHub Enterprise Server access token.

  • Connect CodeBuild to your GitHub account. To do so, you can do one of the following:

    Note

    This only needs to be done if you haven't connected to GitHub for your account.

Step 1: Create a CodeBuild project with a webhook

In this step, you will create a CodeBuild project with a webhook and review it in the GitHub console. You can also choose GitHub Enterprise as your source provider. To learn more about creating a webhook within GitHub Enterprise, see GitHub manual webhooks.

To create a CodeBuild project with a webhook
  1. Open the Amazon CodeBuild console at https://console.amazonaws.cn/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.

      • For Repository, choose Repository in my GitHub account.

      • For Repository URL, enter https://github.com/user-name/repository-name.

      Note

      By default, your project will only receive WORKFLOW_JOB_QUEUED events for a single repository. If you would like to receive events for all repositories within an organization or enterprise, see GitHub global and organization webhooks.

    • In Primary source webhook events:

      • For Webhook - optional, select Rebuild every time a code change is pushed to this repository.

      • For Event type, select WORKFLOW_JOB_QUEUED. Once this is enabled, builds will only be triggered by GitHub Actions workflow jobs events.

        Note

        CodeBuild will only process GitHub Actions workflow jobs events if a webhook has filter groups containing the WORKFLOW_JOB_QUEUED event filter.

        Build configuration to only be triggered by GitHub Actions workflow jobs events.
    • 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

    • In Buildspec:

      • Note that your Buildspec will be ignored. Instead, CodeBuild will override it to use commands that will setup the self-hosted runner. This project’s primary responsibility is to set up a self-hosted runner in CodeBuild to run GitHub Actions workflow jobs.

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

  4. Open the GitHub console at https://github.com/user-name/repository-name/settings/hooks to verify that a webhook has been created and is enabled to deliver Workflow jobs events.

Step 2: Update your GitHub Actions workflow YAML

In this step, you will update your GitHub Actions workflow YAML file in GitHub to configure your build environment and use GitHub Actions self-hosted runners in CodeBuild. For more information, see Using labels with self-hosted runners.

Update your GitHub Actions workflow YAML

Navigate to GitHub and update the runs-on setting in your GitHub Actions workflow YAML to configure your build environment. To do so, you can do one of the following:

  • You can specify the project name and run ID, in which case the build will use your existing project configuration for the compute, image, image version, and instance size. The project name is needed to link the Amazon-related settings of your GitHub Actions job to a specific CodeBuild project. By including the project name in the YAML, CodeBuild is allowed to invoke jobs with the correct project settings. By providing the run ID, CodeBuild will map your build to specific workflow runs and stop the build when the workflow run is cancelled. For more information, see github context.

    runs-on: codebuild-<project-name>-${{ github.run_id }}-${{ github.run_attempt }}
    Note

    Make sure that your <project-name> matches the name of the project that you created in the previous step. If it doesn't match, CodeBuild will not process the webhook and the GitHub Actions workflow might hang.

    The following is an example of a GitHub Actions workflow YAML:

    name: Hello World on: [push] jobs: Hello-World-Job: runs-on: codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }} steps: - run: echo "Hello World!"
  • You can also override your image and compute type in the label. This will override the environment settings on your project. To override your environment settings for an Amazon EC2 compute build, use the following syntax:

    runs-on: codebuild-<project-name>-${{ github.run_id }}-${{ github.run_attempt }}-<image>-<image-version>-<instance-size>

    To override your environment settings for a Lambda compute build, use the following syntax:

    runs-on: codebuild-<project-name>-${{ github.run_id }}-${{ github.run_attempt }}-<environment-type>-<runtime-version>-<instance-size>

    The following is an example of a GitHub Actions workflow YAML:

    name: Hello World on: [push] jobs: Hello-World-Job: runs-on: codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}-arm-3.0-small steps: - run: echo "Hello World!"
  • You can override the fleet used for your build in the label. This will override the fleet settings configured on your project to use the specified fleet. For more information, see Working with reserved capacity in Amazon CodeBuild. To override your fleet settings for an Amazon EC2 compute build, use the following syntax:

    runs-on: codebuild-<project-name>-${{ github.run_id }}-${{ github.run_attempt }}-fleet-<fleet-name>

    To override both the fleet and the image used for the build, use the following syntax:

    runs-on: codebuild-<project-name>-${{ github.run_id }}-${{ github.run_attempt }}-<image>-<image-version>-fleet-<fleet-name>

    The following is an example of a GitHub Actions workflow YAML:

    name: Hello World on: [push] jobs: Hello-World-Job: runs-on: codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}-arm-3.0-fleet-myFleet steps: - run: echo "Hello World!"
Note

If a dependency provided by GitHub-hosted runners is unavailable in the CodeBuild environment, you can install the dependency using GitHub Actions in your workflow run. For example, you can use the setup-python action to install Python for your build environment.

Supported compute images

In your label, you can override your Amazon EC2 environment settings by using the values in the first three columns. CodeBuild provides the following Amazon EC2 compute images:

Image Image version Instance size Platform Image identifier Definition

linux

4.0

small

medium

large

xlarge

2xlarge

gpu_small

gpu_large

Amazon Linux 2 aws/codebuild/amazonlinux2-x86_64-standard:4.0 al2/standard/4.0

linux

5.0

Amazon Linux 2023 aws/codebuild/amazonlinux2-x86_64-standard:5.0 al2/standard/5.0

arm

2.0

small

medium

large

xlarge

2xlarge

Amazon Linux 2 aws/codebuild/amazonlinux2-aarch64-standard:2.0 al2/aarch64/standard/2.0

arm

3.0

Amazon Linux 2023 aws/codebuild/amazonlinux2-aarch64-standard:3.0 al2/aarch64/standard/3.0

ubuntu

5.0

small

medium

large

xlarge

2xlarge

gpu_small

gpu_large

Ubuntu 20.04 aws/codebuild/standard:5.0 ubuntu/standard/5.0

ubuntu

6.0

Ubuntu 22.04 aws/codebuild/standard:6.0 ubuntu/standard/6.0

ubuntu

7.0

Ubuntu 22.04 aws/codebuild/standard:7.0 ubuntu/standard/7.0

windows

1.0

medium

large

Windows Server Core 2019 aws/codebuild/windows-base:2019-1.0 N/A

windows

2.0

Windows Server Core 2019 aws/codebuild/windows-base:2019-2.0 N/A

windows

3.0

Windows Server Core 2019 aws/codebuild/windows-base:2019-3.0 N/A

In addition, you can override your Lambda environment settings by using the following values. For more information about CodeBuild Lambda compute, see Working with Working with Amazon Lambda compute in Amazon CodeBuild. CodeBuild supports the following Lambda compute images:

Environment type Runtime version Instance size

linux-lambda

dotnet6

go1.21

corretto11

corretto17

corretto21

nodejs18

nodejs20

python3.11

python3.12

ruby3.2

1GB

2GB

4GB

8GB

10GB

arm-lambda

For more information, see Build environment compute modes and types and Docker images provided by CodeBuild.

Step 3: Review your results

Whenever a GitHub Actions workflow run occurs, CodeBuild would receive the workflow job events through the webhook. For each job in the workflow, CodeBuild starts a build to run an ephemeral GitHub Actions runner. The runner is responsible for executing a single workflow job. Once the job is completed, the runner and the associated build process will be immediately terminated.

To view your workflow job logs, navigate to your repository in GitHub, choose Actions, choose your desired workflow, and then choose the specific Job that you'd like to review the logs for.

You can review the requested labels in the log while the job is waiting to be picked up by a self-hosted runner in CodeBuild.

Loading the log of the job.

Once the job is completed, you will be able to view the log of the job.

The log of the job.

About CodeBuild-hosted GitHub Actions runner

When should I include the image and instance overrides in the label?

You can include the image and instance overrides in the label in order to specify different build environment for each of your GitHub Actions workflow jobs. This can be done without the need to create multiple CodeBuild projects or webhooks. For example, this is useful when you need to use a matrix for your workflow jobs.

name: Hello World on: [push] jobs: Hello-World-Job: runs-on: codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.os }} strategy: matrix: os: [arm-3.0-small, al2-5.0-large] steps: - run: echo "Hello World!"
Note

Quotation marks might be required if runs-on has multiple labels containing GitHub Actions context.

Can I use Amazon CloudFormation for this feature?

Yes, you can include a filter group in your Amazon CloudFormation template that specifies a GitHub Actions workflow job event filter in your project webhook.

Triggers: Webhook: true FilterGroups: - - Type: EVENT Pattern: WORKFLOW_JOB_QUEUED

For more information, see Filter GitHub webhook events (Amazon CloudFormation).

If you need help setting up project credentials in your Amazon CloudFormation template, see AWS::CodeBuild::SourceCredential in the Amazon CloudFormation User Guide for more information.

How can I mask secrets when using this feature?

By default, secrets that are printed in the log is not masked. If you would like to mask your secrets, you can use the following syntax: ::add-mask::value. The following is an example of how you can use this syntax in your YAML:

name: Secret Job on: [push] jobs: Secret-Job: runs-on: codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }} env: SECRET_NAME: "secret-name" steps: - run: echo "::add-mask::$SECRET_NAME"

For more information, see Masking a value in a log on GitHub.

Which regions support using a CodeBuild-hosted GitHub Actions runner?

CodeBuild-hosted GitHub Actions runners are supported in all CodeBuild regions. For more information about Amazon Web Services Regions where CodeBuild is available, see Amazon Services by Region.

Which platforms support using a CodeBuild-hosted GitHub Actions runner?

CodeBuild-hosted GitHub Actions runners are supported on both Amazon EC2 and Amazon Lambda compute. You can use the following platforms: Amazon Linux 2, Amazon Linux 2023, Ubuntu, and Windows Server Core 2019. For more information, see EC2 compute images and Lambda compute images.

Troubleshooting: How do I troubleshoot if the webhook isn’t working?

Issue: Your webhook isn't working or your workflow job is hanging on GitHub.

Possible cause: Your webhook Workflow jobs event might be failing to trigger a build. Review the Response logs to view the response or error message.

Recommended solution: To debug this error, use the following instructions.

  1. Open the GitHub console at https://github.com/user-name/repository-name/settings/hooks to view your repository's webhook settings. On this page, you'll see a webhook that was created for your repository.

  2. Choose Edit and confirm that the webhook is enabled to deliver Workflow jobs events.

    Workflow job events are enabled in your webhook.
  3. Navigate to the Recent Deliveries tab, find the corresponding workflow_job.queued event, and expand the event.

  4. Review the labels field in the Payload and make sure it’s as expected.

  5. Finally, review the Response tab, as this contains the response or error message returned from CodeBuild.

    The response or error message returned from CodeBuild.
  6. Alternatively, you can debug webhook failures using GitHub's APIs. You can view recent deliveries for a webhook using the List deliveries for a repository webhook API:

    gh api \ -H "Accept: application/vnd.github+json" \ -H "X-GitHub-Api-Version: 2022-11-28" \ /repos/owner/repo/hooks/hook-id/deliveries

    After finding the webhook delivery you're looking to debug and noting the delivery ID, you can use the Get a delivery for a repository webhook API. CodeBuild's response to the webhook's delivery payload can be found in the response section:

    gh api \ -H "Accept: application/vnd.github+json" \ -H "X-GitHub-Api-Version: 2022-11-28" \ /repos/owner/repo/hooks/hook-id/deliveries/delivery-id