Writing a buildspec.yml
buildspec.yml tells CodeBuild exactly how to install, build, test, and package your app.
buildspec.yml is the recipe CodeBuild follows. It lists commands grouped into phases and declares which files to hand off as build artifacts.
The phases
- install — set up tools and language runtimes.
- pre_build — log in to ECR, run linters.
- build — compile, bundle, or build the Docker image.
- post_build — push the image, write deployment metadata.
The artifacts section names the files (like an updated ECS task definition) passed to the next pipeline stage.
Example
version: 0.2
phases:
install:
runtime-versions:
nodejs: 20
pre_build:
commands:
- aws ecr get-login-password | docker login --username AWS --password-stdin $ECR_URL
build:
commands:
- npm ci && npm test
- docker build -t $ECR_URL/myapp:$CODEBUILD_RESOLVED_SOURCE_VERSION .
post_build:
commands:
- docker push $ECR_URL/myapp:$CODEBUILD_RESOLVED_SOURCE_VERSION
artifacts:
files:
- imagedefinitions.jsonWhen to use it
- A team writes a buildspec.yml to install dependencies, run tests, build a Docker image, and push it to ECR in a single CodeBuild job.
- A developer uses the reports section of buildspec.yml to publish JUnit test results to CodeBuild so failures are visible in the AWS console.
- An ops engineer uses buildspec environment variables to pass the ECR repository URI from CodePipeline into the build without hardcoding it.
More examples
Basic buildspec.yml
Defines install and build phases for a Node.js project, then packages the dist folder and appspec for CodeDeploy.
version: 0.2
phases:
install:
runtime-versions:
nodejs: 20
commands:
- npm ci
build:
commands:
- npm test
- npm run build
artifacts:
files:
- dist/**/*
- appspec.ymlBuildspec to build and push Docker image
Logs in to ECR, builds the Docker image tagged with the commit SHA, pushes it, and outputs imagedefinitions.json for ECS deploy.
version: 0.2
env:
variables:
REPO_URI: 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp
phases:
pre_build:
commands:
- aws ecr get-login-password | docker login --username AWS --password-stdin $REPO_URI
- GIT_SHA=$(echo $CODEBUILD_RESOLVED_SOURCE_VERSION | cut -c1-7)
build:
commands:
- docker build -t $REPO_URI:$GIT_SHA .
- docker push $REPO_URI:$GIT_SHA
artifacts:
files:
- imagedefinitions.jsonPublish test report in buildspec
Publishes JUnit test results to CodeBuild Reports so pass/fail counts and individual failures appear in the console.
version: 0.2
phases:
build:
commands:
- npm ci
- npm test -- --reporters=jest-junit
reports:
jest-results:
files:
- junit.xml
file-format: JUNITXML
Discussion