Set up self-hosted GitHub Actions runners in AWS 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:
-
If you haven't done so already, create a personal access token or connect with an OAuth app to connect your project to GitHub.
-
Navigate to the CodeBuild console and create a CodeBuild project with a webhook and set up your webhook filters.
-
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 AWS, which provides security and convenience through features like IAM, AWS Secrets Manager integration, AWS CloudTrail, and Amazon VPC. You can access latest instance types, including ARM-based instances.
Topics
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:
-
You can add GitHub as a source provider in the console. You can connect with either an OAuth app or a personal access token. For instructions, see Connect GitHub with an access token (console) .
-
You can import your GitHub credentials via the ImportSourceCredentials API. This can only be done with a personal access token. If you connect using an OAuth app, you must connect using the console instead. For instructions, see Connect GitHub with an access token (CLI) .
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
-
Open the AWS CodeBuild console at https://console.aws.amazon.com/codesuite/codebuild/home
. -
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.
-
-
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.
-
-
-
Continue with the default values and then choose Create build project.
-
Open the GitHub console at
https://github.com/
to verify that a webhook has been created and is enabled to deliver Workflow jobs events.user-name
/repository-name
/settings/hooks
Step 2: Update your GitHub Actions workflow YAML
In this step, you will update your GitHub Actions workflow YAML file in GitHub
Update your GitHub Actions workflow YAML
Navigate to GitHub
runs-on
-
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 AWS-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!"
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
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 |
---|---|---|---|---|---|
|
|
|
Amazon Linux 2 | aws/codebuild/amazonlinux2-x86_64-standard:4.0 |
al2/standard/4.0 |
|
|
Amazon Linux 2023 | aws/codebuild/amazonlinux2-x86_64-standard:5.0 |
al2/standard/5.0 |
|
|
|
|
Amazon Linux 2 | aws/codebuild/amazonlinux2-aarch64-standard:2.0 |
al2/aarch64/standard/2.0 |
|
|
Amazon Linux 2023 | aws/codebuild/amazonlinux2-aarch64-standard:3.0 |
al2/aarch64/standard/3.0 |
|
|
|
|
Ubuntu 20.04 | aws/codebuild/standard:5.0 |
ubuntu/standard/5.0 |
|
|
Ubuntu 22.04 | aws/codebuild/standard:6.0 |
ubuntu/standard/6.0 |
|
|
|
Ubuntu 22.04 | aws/codebuild/standard:7.0 |
ubuntu/standard/7.0 |
|
|
|
|
Windows Server Core 2019 | aws/codebuild/windows-base:2019-1.0 |
N/A |
|
|
Windows Server Core 2019 | aws/codebuild/windows-base:2019-2.0 |
N/A | |
|
|
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 AWS Lambda compute in AWS CodeBuild. CodeBuild supports the following Lambda compute images:
Environment type | Runtime version | Instance size |
---|---|---|
|
|
|
|
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!"
Note
Quotation marks might be required if runs-on
has multiple labels containing GitHub Actions context.
Can I use AWS CloudFormation for this feature?
Yes, you can include a filter group in your AWS 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 (AWS CloudFormation).
If you need help setting up project credentials in your AWS CloudFormation template, see AWS::CodeBuild::SourceCredential in the AWS 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::
. The following is an example of how you can use this syntax in your YAML:value
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
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 AWS Regions
where CodeBuild is available, see AWS 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 AWS 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.
-
Open the GitHub console at
https://github.com/
to view your repository's webhook settings. On this page, you'll see a webhook that was created for your repository.user-name
/repository-name
/settings/hooks -
Choose Edit and confirm that the webhook is enabled to deliver Workflow jobs events.
-
Navigate to the Recent Deliveries tab, find the corresponding
workflow_job.queued
event, and expand the event. -
Review the labels field in the Payload and make sure it’s as expected.
-
Finally, review the Response tab, as this contains the response or error message returned from CodeBuild.