CodeBuild and the Buildspec File

What it is

AWS CodeBuild is a fully managed build service. It starts a fresh container for each build, runs your commands, uploads the output and then discards the container, so you pay only while builds run and have no build servers to patch.

The instructions live in a YAML file called the buildspec. By default CodeBuild looks for buildspec.yml in the root of the source, but you can set another path or paste the buildspec into the project.

How it works

Buildspec structure

The file has a version, optional environment settings, a set of phases, and sections for reports, artifacts and cache. Use version 0.2, which runs each command in the same shell session.

version: 0.2
env:
  variables:
    STAGE: test
  parameter-store:
    API_URL: /myapp/test/api-url
  secrets-manager:
    DB_PASSWORD: myapp/db:password
phases:
  install:
    runtime-versions:
      nodejs: 18
    commands:
      - npm ci
  pre_build:
    commands:
      - npm run lint
  build:
    commands:
      - npm test
      - npm run build
  post_build:
    commands:
      - echo "Build succeeding flag is $CODEBUILD_BUILD_SUCCEEDING"
reports:
  unit-tests:
    files:
      - junit.xml
    file-format: JUNITXML
artifacts:
  base-directory: dist
  files:
    - '**/*'
cache:
  paths:
    - node_modules/**/*

The four phases run in order: install, pre_build, build and post_build. The post_build phase still runs after a failed build phase, so check the CODEBUILD_BUILD_SUCCEEDING variable (1 or 0) before publishing anything from it (the build is still reported as failed).

Secrets and configuration

Plain values go under variables. Sensitive values should come from AWS Systems Manager Parameter Store (parameter-store) or AWS Secrets Manager (secrets-manager), so they never appear in the buildspec or in logs. The build role needs permission to read them.

A Secrets Manager reference has the form secret-id:json-key, with optional version fields after it.

Environment and compute

If a build must reach a private database or a private package repository, place the project in a Virtual Private Cloud (VPC). The VPC needs a route to the internet through a NAT gateway, or VPC endpoints, for the build to download dependencies or reach AWS APIs. A VPC build without that route is a classic timeout cause.

Caching

Caching shortens builds by reusing downloaded dependencies.

Reports

Test and code coverage reports are collected from files your tests write. JUnit XML is a common test format, and coverage formats include JaCoCo and Cobertura. Reports appear in report groups in the console, which gives trend history.

Build output to ECR

A container build usually logs in to ECR, builds, tags and pushes the image in the build and post_build phases. The role needs ECR push rights and privileged mode must be on.

aws codebuild start-build --project-name my-project
aws codebuild batch-get-builds --ids my-project:1234abcd

Batch builds

A batch build runs several builds from one request, either as a list, a graph with dependencies or a matrix. It is used for multi platform builds or parallel test shards.