CodeBuild GitHub Actions Runner Troubleshooting Guide
When a CodeBuild-hosted runner does not pick up a job, the cause is usually the webhook, the label, IAM, VPC, or a build quota. Here is how to isolate each.
Most CodeBuild GitHub Actions runner failures fall into a handful of buckets: the webhook is not delivering, the runs-on label is wrong or mismatched across jobs, the IAM service role lacks a permission, the VPC blocks the runner, the runner token expires, or you hit a concurrent build quota. This guide indexes each with the AWS-documented fix. Verify against the AWS sources linked below, as behavior and docs change.
The job hangs and never starts
According to AWS docs, a hung job usually means the WORKFLOW_JOB_QUEUED webhook did not trigger a build, or the runs-on label does not match your project. Check the webhook first (see the webhook page), then confirm the codebuild-<project>-${{ github.run_id }}-${{ github.run_attempt }} label matches your project name exactly.
Multiple jobs, one gets stuck
According to AWS docs, this happens when jobs in the same run have a different number of label overrides, so GitHub can route one job to the wrong runner. The fix is to give every job the same number of overrides or a unique custom label. See the dedicated label-format page.
Build starts but fails on permissions or networking
Permission failures point at the IAM service role; networking failures (for example an EC2 UnauthorizedOperation) point at VPC configuration. According to AWS docs, both are configured by you in AWS. See the IAM and VPC pages.
Builds queue or are rejected under load
According to AWS docs, CodeBuild enforces per-account, per-Region concurrent build quotas. If you exceed them, builds cannot start. See the concurrency page for the quota-increase path.
Prefer to avoid this class of issue
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.