CodeBuild

Every CodeBuild build follows a defined lifecycle. Understanding the phases is critical for debugging failed builds.

The buildspec.yml file is the heart of CodeBuild. It lives at the root of your repository (or you can inline it in the project definition):

version: 0.2

env:
  variables:
    NODE_ENV: "test"
  secrets-manager:
    DB_PASSWORD: "arn:aws:secretsmanager:us-east-1:123456789:secret:my-secret:password"

phases:
  install:
    runtime-versions:
      nodejs: 18
    commands:
      - npm ci
  pre_build:
    commands:
      - aws ecr get-login-password | docker login --username AWS --password-stdin $ECR_REPO
  build:
    commands:
      - npm run test
      - npm run build
      - docker build -t $ECR_REPO:$CODEBUILD_RESOLVED_SOURCE_VERSION .
      - docker push $ECR_REPO:$CODEBUILD_RESOLVED_SOURCE_VERSION
  post_build:
    commands:
      - echo "Build complete"

artifacts:
  files:
    - '**/*'
  base-directory: dist

cache:
  paths:
    - node_modules/**/*

CodeBuild offers several compute options. Choosing the right size directly affects build duration and cost.

For the build environment image, AWS provides curated images (aws/codebuild/standard:7.0 for latest) or you can bring your own Docker image from ECR or Docker Hub. Custom images let you pre-install tools to reduce install phase time.

CodeBuild supports three caching mechanisms. Caching is one of the most impactful optimizations for build speed.

Define the cache in buildspec.yml under the cache key. S3 cache paths are compressed and stored as zip files named by a hash of the cache key.

# In buildspec.yml - cache node_modules to S3
cache:
  paths:
    - node_modules/**/*
    - .npm/**/*

# In CodeBuild project (console/Terraform) - enable S3 cache
# cache:
#   type: S3
#   location: my-bucket/codebuild-cache

By default, CodeBuild runs in an AWS-managed network with internet access. When builds need to reach resources inside your VPC (RDS, internal APIs, Elasticache), you must configure VPC mode.

The CodeBuild service role needs permissions for everything the build does. Common additions beyond the AWS-managed policy:

# Common IAM additions for CodeBuild service role
# ECR push/pull
ecr:GetAuthorizationToken
ecr:BatchCheckLayerAvailability
ecr:InitiateLayerUpload
ecr:UploadLayerPart
ecr:CompleteLayerUpload
ecr:PutImage

# Secrets Manager
secretsmanager:GetSecretValue

# Parameter Store
ssm:GetParameters
ssm:GetParametersByPath

# S3 artifact bucket
s3:GetObject
s3:PutObject
s3:GetBucketAcl
s3:GetBucketLocation

Billing is per minute, rounded up. The free tier includes 100 build minutes per month on BUILD_GENERAL1_SMALL.

Cost optimization strategies: use S3 caching to reduce build duration; use the smallest compute type that completes within an acceptable time; parallelize test suites using batch builds rather than running them sequentially.