Fix: CodeBuild Runner VPC and Networking Errors
Running CodeBuild in a VPC gives you private AWS access, but the runner still needs the right EC2 permissions, subnets, and egress. Here is what AWS documents.
According to AWS CodeBuild docs, CodeBuild can run inside your VPC to reach private resources such as RDS or ElastiCache, which is a real strength. The trade-off is that you own the network configuration, and misconfiguration produces specific errors. This page covers the VPC-side failures for CodeBuild-hosted GitHub Actions runners.
UnauthorizedOperation on EC2
According to AWS docs, if CodeBuild lacks the EC2 permissions required to work with a VPC, you can get an Unexpected EC2 error: UnauthorizedOperation. Grant the CodeBuild service role the EC2 network permissions needed to create and manage the network interfaces used by builds in the VPC.
Subnet and availability-zone rules
According to AWS guidance, the subnets and security groups you attach must belong to the selected VPC, and provided subnets should be in different Availability Zones. A VPC config that violates this can prevent builds from starting.
Egress to reach GitHub and download the runner
The ephemeral runner must reach GitHub to register and pick up the job, and download the runner agent. According to community reports referenced in AWS re:Post, a private subnet without a NAT gateway or the right endpoints can leave the runner unable to reach the internet; one reported symptom was the runner archive downloading as an error document instead of the expected file, which points at blocked egress or a proxy in the VPC path.
The managed contrast
This class of VPC wiring is inherent to running CI inside your own AWS network, and it is the price of native in-VPC access. If you do not need private AWS resource access, Latchkey managed runners avoid VPC setup entirely, which is one reason some teams move non-VPC jobs off CodeBuild.