Tutorial: Configure a CodeBuild-hosted GitHub Actions runner

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 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 }}

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 available images. 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 }}
      - image:arm-3.0
      - instance-size:small
    steps:
      - run: echo "Hello World!"

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.

CodeBuild will not run buildspec commands during the BUILD phase, as the self-hosted runner runs in the BUILD phase.

CodeBuild will not download any primary or secondary sources during the DOWNLOAD_SOURCE phase. If you have a buildspec file configured, only that file will be downloaded from the project's primary source.

If a build command fails in the PRE_BUILD or INSTALL phase, CodeBuild will not start the self-hosted runner and the GitHub Actions workflow job will need to be cancelled manually.

CodeBuild fetches the runner token during the DOWNLOAD_SOURCE phase, which has an expiration time of one hour. If your PRE_BUILD or INSTALL phases exceed an hour, the runner token may expire before the GitHub self-hosted runner starts.