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

Set up 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:

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:

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.

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:

Supported compute images

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

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.

Once the job is completed, you will be able to view 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!"

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.

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.