Tutorial: Configure a CodeBuild-hosted GitHub Actions runner - AWS CodeBuild
View a markdown version of this page Documentation AWS CodeBuild User Guide Step 1: Create a CodeBuild project with a webhook Step 2: Update your GitHub Actions workflow YAML Step 3: Review your results GitHub Actions runner configuration options Filter GitHub Actions webhook events (CloudFormation) Filter GitHub Actions webhook events (AWS CDK) Filter GitHub Actions webhook events (Terraform) Filter GitHub Actions webhook events (AWS CLI) Tutorial: Configure a CodeBuild-hosted GitHub Actions runner This tutorial shows you how to configure your CodeBuild projects to run GitHub Actions jobs.
For more information about using GitHub Actions with CodeBuild see Tutorial: Configure a CodeBuild-hosted GitHub Actions runner. To complete this tutorial, you must first: Connect with a personal access token, a Secrets Manager secret, OAuth app, or GitHub App. 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 in CodeBuild . 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 a personal access token, a Secrets Manager secret, OAuth app, or GitHub App. For instructions, see GitHub and GitHub Enterprise Server access in CodeBuild . 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 Project type , choose Runner project .
In Runner : For Runner provider , choose GitHub . For Runner location , choose Repository . For Repository URL under Repository , choose 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 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 unless buildspec-override:true is added as a label. Instead, CodeBuild will override it to use commands that will set up the self-hosted runner.
Continue with the default values and then choose Create build project . 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 and Label overrides supported with the CodeBuild-hosted GitHub Actions runner . 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 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 maps your build to specific workflow runs and stops the build when the workflow run is canceled. 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. See Compute images supported with the CodeBuild-hosted GitHub Actions runner for a list of curated images.
For using custom images, see Label overrides supported with the CodeBuild-hosted GitHub Actions runner . The compute type and image in the label will override the environment settings on your project. To override your environment settings for an CodeBuild EC2 or Lambda compute build, use the following syntax: runs-on: - codebuild- <project-name> -$ { { github.run_id }}-$ { { github.run_attempt }} image: <environment-type> - <image-identifier> instance-size: <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 }} image:arm-3.0 instance-size: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 Run builds on reserved capacity fleets . 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 }} fleet: <fleet-name> image: <environment-type> - <image-identifier> 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 }} fleet:myFleet image:arm-3.0 steps: - run: echo "Hello World!" In order to run your GitHub Actions jobs on a custom image, you can configure a custom image in your CodeBuild project and avoid providing an image override label.
CodeBuild will use the image configured in the project if no image override label is provided. Optionally, you can provide labels outside of those that CodeBuild supports. These labels will be ignored for the purpose of overriding attributes of the build, but will not fail the webhook request. For example, adding testLabel as a label will not prevent the build from running. 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. Run buildspec commands in the INSTALL, PRE_BUILD, and POST_BUILD phases
The rest of this page is on the live site.