Fix: Wrong runs-on Label Format for CodeBuild Runners
A single wrong character in the runs-on label leaves a CodeBuild job hanging. Here is the exact format and the label-count trap AWS documents.
According to AWS CodeBuild docs, the runs-on label ties a GitHub Actions job to a specific CodeBuild project, and a mismatch means CodeBuild will not process the webhook and the job may hang. A separate but common failure is mismatched label counts across jobs in one run. This page covers both.
The exact required format
According to AWS docs, use: runs-on: codebuild-<project-name>-${{ github.run_id }}-${{ github.run_attempt }}. The <project-name> must exactly match your CodeBuild Runner project. AWS docs warn that if it does not match, CodeBuild will not process the webhook and the workflow job might hang.
Why run_id and run_attempt matter
According to AWS docs, including github.run_id and github.run_attempt lets CodeBuild map each build to a specific workflow run and stop the build if that run is cancelled. Omitting them breaks that mapping.
The mismatched-label-count trap
According to AWS docs, if two jobs in the same run have a different number of labels, GitHub can route a job to the wrong runner. Example: Job 1 has only the base codebuild label, Job 2 adds instance-size:medium. Job 1 can be picked up by either runner, but if it takes Job 2 runner, Job 2 gets stuck because Job 1 runner lacks the instance-size:medium label.
The fix: same count or unique labels
According to AWS docs, give every job the same number of label overrides, or assign each job a unique custom label such as job1 and job2. AWS notes that a unique per-job label is the most reliable option, because it ensures no job set of labels is a subset of another, so GitHub matches each job only to its own runner.
Override labels are order-sensitive to structure
According to AWS docs, overrides like image:arm-3.0, instance-size:small, fleet:<name>, and buildspec-override:true are added as additional labels on the runs-on list. Unsupported extra labels are ignored rather than failing the webhook, but they still count toward the label-count matching described above.