How to Set Up a CodeBuild-Hosted GitHub Actions Runner
CodeBuild can act as a self-hosted GitHub Actions runner host. Here is the setup, drawn from AWS docs, plus the exact runs-on label format.
According to AWS CodeBuild docs, you can run GitHub Actions jobs on CodeBuild by creating a Runner-type project, connecting GitHub, and letting a WORKFLOW_JOB_QUEUED webhook start an ephemeral runner per job. This guide walks the setup and the label format that ties a workflow job to your project. Verify details against the AWS source linked at the end, as AWS updates its docs.
Prerequisites: connect GitHub
According to AWS CodeBuild docs, first connect CodeBuild to GitHub using a personal access token, a Secrets Manager secret, an OAuth app, or a GitHub App. OAuth app connections must be set up in the CodeBuild console; a personal access token can be imported via the ImportSourceCredentials API. You only need to do this once per account.
Step 1: Create a Runner-type CodeBuild project
In the CodeBuild console, create a build project and choose the Runner project type. Set Runner provider to GitHub and Runner location to Repository (or configure an organization or enterprise webhook to receive events across repos). According to AWS docs, by default the project only receives WORKFLOW_JOB_QUEUED events for a single repository.
Step 2: Choose environment and compute
Pick a supported Environment image and Compute type. According to AWS docs, you can override these per job from the workflow YAML label, so the project setting is a default. Note that your buildspec is ignored unless you add buildspec-override:true as a label, because CodeBuild replaces it with commands that set up the ephemeral self-hosted runner.
Step 3: Confirm the webhook
After creating the project, open your repository webhook settings on GitHub and confirm a webhook exists and is enabled to deliver Workflow jobs events. According to AWS docs, CodeBuild receives each workflow_job.queued event and starts a build that runs an ephemeral runner for that single job, then terminates it.
Step 4: Set the runs-on label
Point your workflow job at the project with the CodeBuild label. According to AWS docs, the format is: runs-on: codebuild-<project-name>-${{ github.run_id }}-${{ github.run_attempt }}. The project name must exactly match the project you created; AWS docs warn that a mismatch means CodeBuild will not process the webhook and the job may hang. The run_id and run_attempt let CodeBuild map builds to workflow runs and stop a build when a run is cancelled.
Step 5 (optional): Override image, size, or fleet
According to AWS docs, you can append overrides to the label, for example image:arm-3.0 and instance-size:small, or fleet:<fleet-name> to run on a reserved-capacity fleet. Supported environment types include linux, linux-ec2, arm, arm-ec2, ubuntu, windows, windows-ec2, linux-lambda, and arm-lambda, with GPU-capable instance sizes gpu_small and gpu_large on some Linux images.
A managed alternative
If you would rather not stand up and operate CodeBuild in your own AWS account, Latchkey is a fully-managed alternative: you change one runs-on label and run your existing GitHub Actions jobs on managed, self-healing runners with no AWS account, IAM role, VPC, or webhook to configure. It is one option to weigh, not a knock on CodeBuild.