AWS CodeBuild

What CodeBuild is

CodeBuild is a fully managed continuous-integration build service. You create a “project” that points at a source — CodeCommit, S3, GitHub, GitLab, or Bitbucket — and hand it a buildspec, a YAML file of shell commands. On each build it spins up a fresh, ephemeral container, clones the source, runs your compile/test/package steps, uploads the resulting artifacts (usually to S3), and throws the container away. There are no build servers to provision, patch, or scale, and you pay per build-minute for the compute size you pick.

It’s specifically a build service, not a deploy service: it produces artifacts. Getting those artifacts onto servers is CodeDeploy’s or a pipeline deploy action’s job. Design Beaver models CodeBuild as an external, API-accessed build node and validates as you draw — so it knows the source, artifact, and IAM edges a build actually needs, and which ones don’t exist.

When to use CodeBuild (and when not to)

Reach for CodeBuild when you want managed, ephemeral CI compute and don’t want to run and patch your own build fleet. It fits the build/test stage of an AWS pipeline that plugs straight into CodePipeline, and it fits bursty workloads where you’d rather pay per build-minute than keep an always-on build box idle between commits. It also gives you a build that runs under an IAM role and can optionally reach private resources inside your VPC during tests.

Don’t reach for it when you only need to deploy already-built artifacts — that’s CodeDeploy or a pipeline deploy action, not a build service. Skip it if you want a full end-to-end release orchestrator with stages and approvals, because that’s CodePipeline and CodeBuild is one action inside it. It’s also the wrong choice if your team is already standardized on an external CI like GitHub Actions or GitLab CI and doesn’t want a second build system, or if the workload is a long-running service rather than a finite build job — CodeBuild containers are ephemeral and time-boxed.

Variants: compute model, not instance sizes

The choice that matters up front isn’t a compute SKU — it’s how the build compute is provisioned and billed. CodeBuild also offers many prebuilt images, GPU compute, and per-size tiers not listed here.

CodeBuild pricing in plain English

You pay per build-minute for on-demand builds at a rate that scales with the compute size, and nothing when no build runs; reserved-capacity fleets and Lambda compute are billed on their own models. Cache dependencies and layers so they aren’t rebuilt every run, pick the smallest compute size that works, and prefer ARM/Graviton compute where your toolchain supports it.

How CodeBuild connects to other services

CodeBuild’s build container runs under a service role you attach to the project, and almost every AWS connection it makes is that role’s credentials being used automatically inside the build. The recurring theme is to grant the service role the specific, scoped actions a build needs, never to bake access keys into the buildspec. Design Beaver models each of these edges — including the easy-to-miss ones, like the sts:GetServiceBearerToken that CodeArtifact logins require on top of the codeartifact:* actions.

• →CodeCommitsecurity

  CodeBuild clones the source code (and buildspec) for the project from a CodeCommit repository at the start of a build

  IAM:codecommit:GitPull

• →S3security

  CodeBuild uploads build output artifacts to an S3 bucket, reads/writes an S3 build cache, and can pull the source itself from an S3 object (zip or folder)

  IAM:s3:GetObjects3:GetObjectVersions3:PutObjects3:GetBucketAcls3:GetBucketLocation

• →ECRsecurity

  CodeBuild pulls a custom build-environment image from a private ECR repository to run the build in, and/or builds a Docker image during the build and pushes it back to ECR

  IAM:ecr:GetAuthorizationTokenecr:BatchCheckLayerAvailabilityecr:GetDownloadUrlForLayerecr:BatchGetImageecr:InitiateLayerUploadecr:UploadLayerPartecr:CompleteLayerUploadecr:PutImage

• →CodeArtifactsecurity

  During a build, CodeBuild authenticates to a CodeArtifact repository to pull private packages (npm, pip, Maven, NuGet) — and optionally publish built packages back to it

  IAM:codeartifact:GetAuthorizationTokencodeartifact:GetRepositoryEndpointcodeartifact:ReadFromRepositorysts:GetServiceBearerToken

• →Secrets Managersecurity

  CodeBuild pulls sensitive build values — private-registry credentials, API tokens, signing keys — from Secrets Manager instead of storing them as plaintext environment variables

  IAM:secretsmanager:GetSecretValue

• ←CodePipeline

  CodePipeline invokes a CodeBuild project as a Build or Test action in a stage — the standard way CI runs inside an AWS release pipeline. CodePipeline hands CodeBuild the stage's input artifact and collects its output artifact for the next stage

What CodeBuild can’t connect to

Some edges look reasonable on a canvas but don’t exist in AWS. Design Beaver flags them instead of letting you draw a diagram that can’t be built.

• ✕CodeDeploy

  CodeBuild and CodeDeploy do not connect directly — CodeBuild produces build artifacts (typically to S3) and CodeDeploy consumes an artifact to deploy it, but nothing calls from one to the other. The handoff is orchestrated by CodePipeline, which takes CodeBuild's output artifact and feeds it to a CodeDeploy deploy action. Draw the edges through CodePipeline (or the shared S3 artifact bucket), not as a CodeBuild-to-CodeDeploy line.

Anti-patterns Design Beaver catches

These are the CodeBuild mistakes that pass a diagram review but bite in production — the ones the validation engine flags as you draw.

Gotchas that bite in production

• Plaintext env vars leak. PLAINTEXT-type environment variables show up in clear text in the console and CLI and can end up in build logs. Anything sensitive belongs in a SECRETS_MANAGER or PARAMETER_STORE env var or a buildspec secrets reference, not a plaintext project variable.
• Docker builds need privileged mode. docker build and docker push inside a CodeBuild container require the Docker daemon, which only runs when the project’s privileged flag is on. Without it, Docker commands just fail.
• The service role is a real attack surface. The build runs arbitrary commands from your buildspec and source, so a role with s3:*, ecr:*, or Action: * lets a compromised build reach far past what it needs. Scope it to the concrete actions and resources each build actually uses.
• CodeArtifact needs an STS permission too. It’s easy to grant the codeartifact:* actions and forget sts:GetServiceBearerToken — without it, GetAuthorizationToken fails and the package-manager login won’t work.
• VPC access is optional and per-project. CodeBuild isn’t subnet-resident, but you can attach a build to a VPC to reach private resources like a test database. That’s a project setting with its own subnet, security-group, and route considerations — and a NAT path if the build needs the internet — not the default.

Further reading

• Official AWS documentation
• Why we built a validation engine