AWS CodeBuild

Managed build service — compiles code, runs tests, produces artifacts/Docker images. The build stage of the AWS-native CI/CD trio (CodePipeline orchestrates, CodeBuild builds, CodeDeploy deploys). Tier 3 for most backend roles — GitHub Actions / GitLab CI dominate the broader market — but relevant in AWS-native shops.

What it is

A fully managed build environment. You define the build steps in a buildspec.yml; CodeBuild spins up a container, runs the phases, and produces artifacts. No build servers to maintain.

# buildspec.yml
version: 0.2
phases:
  install:
    runtime-versions:
      python: 3.12
    commands:
      - pip install -r requirements.txt
  pre_build:
    commands:
      - pip install pytest ruff
      - ruff check .
  build:
    commands:
      - pytest --cov=app
      - docker build -t $ECR_REPO:$CODEBUILD_RESOLVED_SOURCE_VERSION .
  post_build:
    commands:
      - aws ecr get-login-password | docker login --username AWS --password-stdin $ECR_REGISTRY
      - docker push $ECR_REPO:$CODEBUILD_RESOLVED_SOURCE_VERSION
artifacts:
  files:
    - appspec.yml
    - taskdef.json

Phases run in order: install → pre_build → build → post_build. A non-zero exit in any phase fails the build.

Build environment

• Runs in a Docker container — AWS-managed images (with common runtimes) or your own custom image from ECR.
• You pick compute size (CPU/memory); larger = faster builds = more cost per minute.
• Building Docker images needs privileged mode enabled on the project.
• Billed per build-minute — no idle cost (unlike a self-hosted Jenkins box).

IAM — the service role

CodeBuild assumes a service role for everything it does in your account: pull source, push to ECR, write logs to CloudWatch, read secrets. A common failure is a build that fails at docker push or secret retrieval because the service role is missing ecr:* or secretsmanager:GetSecretValue / kms:Decrypt.

Secrets in a build come from Secrets Manager / SSM Parameter Store referenced in the buildspec env section — never hardcoded.

Caching

Builds re-download dependencies every time unless you configure caching:

• S3 cache — cache pip/npm directories or Docker layers to S3 between builds.
• Local cache — cache on the build host (faster, but only helps if the same host is reused).

Without caching, every build re-runs pip install from scratch — slow and wasteful.

Where it fits — the AWS CI/CD trio

CodePipeline   orchestrates the stages (source → build → deploy)
   │
   ├─ Source:  CodeCommit / GitHub / S3 — triggers the pipeline on commit
   ├─ Build:   CodeBuild — buildspec.yml: test, lint, build image, push to ECR
   └─ Deploy:  CodeDeploy — rolls out to ECS / Lambda / EC2 (rolling, blue/green, canary)

• CodePipeline — the orchestrator; defines the stage graph.
• CodeBuild — the build/test stage.
• CodeDeploy — the deployment stage; handles deployment strategies and rollback.

CodeBuild vs GitHub Actions

For most teams, GitHub Actions (with OIDC federation to AWS — see IAM — Advanced Role Patterns) is the default. CodeBuild earns its place when builds need to run inside your VPC (access private resources during the build) or when you’re committed to the AWS-native pipeline.

Common gotchas

• Service role missing permissions — build fails at docker push (no ecr:*) or at secret retrieval (no secretsmanager / kms:Decrypt).
• No caching — every build re-downloads all dependencies; slow and costs build-minutes.
• Privileged mode not enabled — docker build fails inside the build container.
• Secrets hardcoded in buildspec — reference Secrets Manager / SSM instead.
• Wrong phase for a command — a test in install runs before dependencies are ready; understand the phase order.