CodeBuild and the Buildspec file

Welcome — this lesson explains AWS CodeBuild and the central role of the buildspec.yml file for defining build steps in a CI workflow. At a high level, AWS CodeBuild is a fully managed continuous integration (CI) service that runs your build, test, and artifact creation steps. A commit to a source repository (for example, CodeCommit, GitHub, or another provider) typically triggers a CodeBuild project. CodeBuild executes the commands in your buildspec.yml, produces artifacts (for Docker images this often means pushing to Amazon ECR), and streams build logs to CloudWatch Logs so you can monitor and troubleshoot.

Diagram of an AWS CI workflow: a developer pushes code to AWS CodeCommit which triggers AWS CodeBuild, storing build artifacts in Amazon S3 and logs in AWS CloudWatch.

CodeBuild focuses on continuous integration—building, testing, and packaging artifacts. Deployments are usually handled by other services (for example, CodeDeploy, Elastic Beanstalk, or a later stage in CodePipeline). CodeBuild supports many managed runtime environments (Java, Python, Node, Ruby, Go, Rust, etc.) and also allows fully custom Docker images when you need a specialized toolchain or runtime. Key features:

Fully managed CI / build service.
Managed runtime environments plus support for custom build images.
Tight integration with AWS services (IAM, CodePipeline, CodeDeploy, CloudWatch).
Parallel and batch builds to run multiple configurations concurrently.

A presentation slide titled "CodeBuild – Features" showing five colorful icons and cards. The cards list features: fully managed continuous integration service, wide and customizable build environments, integration with AWS services, and parallel builds.

Buildspec phases — the core of CodeBuild

The buildspec.yml file (placed at the repository root by convention) defines the commands and environment settings that CodeBuild runs inside the build container. Focus on these four primary phases:

Phase	Purpose
`install`	Install dependencies, runtime setup, and tools required for later phases.
`pre_build`	Preparation steps such as running unit tests, linting, or gathering runtime metadata (e.g., account ID).
`build`	Main build actions: compile, package, or build Docker images.
`post_build`	Finalization steps: push artifacts to registries, notify downstream systems, or write metadata.

There are additional lifecycle steps managed by the service (for example, source download before install and artifact upload after post_build), but the buildspec.yml controls what runs inside the worker during the four main phases.

A presentation slide titled "Buildspec Phase" showing four numbered points about buildspec phases. It says the core phases are install, pre-build, build, and post-build, notes other phases handle tasks like source download and artifact upload, and advises focusing on these four for the DevOps Pro exam.

Example `buildspec.yml`

This example demonstrates the four main sections. It installs Python dependencies, runs tests during pre_build, builds a Docker image during build, and pushes the image to ECR during post_build. Make sure AWS_DEFAULT_REGION is available in the build environment (set via environment variables or project settings).

version: 0.2

phases:
  install:
    runtime-versions:
      python: 3.8
    commands:
      - pip install -r requirements.txt
      - pip install pytest
  pre_build:
    commands:
      - pytest
      # Determine the account ID at runtime (CodeBuild does not automatically provide AWS_ACCOUNT_ID)
      - ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
  build:
    commands:
      - echo "Logging in to Amazon ECR..."
      - aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com
      - docker build -t my-python-app .
      - docker tag my-python-app:latest $ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/my-python-app:latest
  post_build:
    commands:
      - docker push $ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/my-python-app:latest

Notes about this example:

version: 0.2 is the current recommended buildspec schema.
Use install to set up runtimes and tools your build requires.
pre_build is a great place for tests, linting, and gathering environment metadata for later phases.
build contains the primary build logic (for Docker, building and tagging images).
post_build commonly pushes artifacts or triggers downstream actions. CodeBuild will also upload artifacts to the project’s configured artifact location automatically when configured.

Security: Execution role and permissions

CodeBuild runs with an IAM service role (the project’s service role). Grant only the permissions necessary for the build to run—least privilege:

ECR: ecr:GetAuthorizationToken, ecr:BatchCheckLayerAvailability, ecr:PutImage, ecr:InitiateLayerUpload, etc., if pushing/pulling images.
S3: read/write access to artifact buckets if using S3 artifacts or caching.
CodeCommit / GitHub: permissions to access private repositories when needed.
CloudWatch Logs: logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents so CodeBuild can create and publish logs.

Always ensure the CodeBuild service role has the minimum IAM permissions required for the build operations your project performs (ECR push/pull, S3 artifact access, publishing logs/metrics, or calling other AWS APIs).

A slide screenshot titled "CodeBuild – Security and IAM Roles" showing the AWS IAM Permissions tab listing attached managed policies (e.g., AmazonElasticContainerRegistryPublicFullAccess, AWSCodeCommitFullAccess, CloudWatchFullAccess). The console shows options to simulate, remove, and add permissions and a filter/search for policies.

If CloudWatch Logs permissions are missing, CodeBuild cannot create log groups or streams. Confirm the service role includes logs:CreateLogGroup, logs:CreateLogStream, and logs:PutLogEvents to ensure build logs are delivered to CloudWatch.

Full CodeBuild lifecycle

The buildspec.yml controls the phases inside the build container, but the full lifecycle includes additional service-managed steps:

Job submission and worker provisioning
Source download
Execution of install / pre_build / build / post_build
Artifact upload and build completion reporting

Failures can occur in provisioning, source download, or during the install phase and will cause the build to fail early. CloudWatch Logs and the CodeBuild console show lifecycle events and status for troubleshooting.

A vertical flowchart titled "CodeBuild Lifecycle." It shows sequential build stages from SUBMITTED to COMPLETED with arrows indicating succeeded/failed outcomes at each step.

Managed images and custom images

CodeBuild offers both managed build environments and support for custom Docker images:

Option	When to use
Managed images	Standard runtimes and common language environments (Amazon Linux, Ubuntu, Windows). Quick setup and maintenance-free.
Custom images	When you need a specific toolchain, architecture (ARM vs x86), GPU support, or strict environment standardization. Custom images can be stored in ECR or external registries.

Note: CodeBuild runs on managed build instances (not Lambda). Select the compute type (CPU/memory) that matches your build workload and ensure the service role can access your chosen image registry.

A screenshot of an AWS CodeBuild environment image settings page showing options for Managed or Custom images, compute choices (EC2 or Lambda), and a running-mode dropdown with OS options like Amazon Linux, Ubuntu, and Windows Server 2019.

Most organizations use custom images to standardize toolchains across builds. Make sure repository and IAM permissions allow CodeBuild to pull these images.

Caching

CodeBuild supports caching to speed up builds by reusing dependencies, Docker layers, and other artifacts. Cache options include:

Local caches (container-local): Docker layer cache, source cache.
S3 cache: Shared cache across build instances.

Configure caching in project settings and reference directories in your buildspec.yml to preserve files between builds.

A slide titled "CodeBuild Caching Mechanism" showing a settings panel. The Cache type is set to "Local" and three checkbox options are listed: Docker layer cache, Source cache, and Custom cache.

Integration with deployment and pipelines

CodeBuild is commonly used as the build/test stage in CodePipeline. After a successful build stage, the pipeline can continue to deployment services (for example, CodeDeploy, ECS, EKS, or CloudFormation) to promote artifacts to QA or production.

A diagram of an AWS CI/CD pipeline showing AWS CodeCommit → AWS CodeBuild → AWS CodeDeploy inside an AWS CodePipeline, with the output deployed to a QA environment. The pipeline icons are purple and the QA target is an orange icon.

Use CodePipeline (or other orchestration tools) to chain builds into multi-stage CI/CD workflows.

Logs and monitoring

CodeBuild automatically ships build logs to CloudWatch Logs and publishes metrics (build durations, success/failure counts) to CloudWatch. For troubleshooting, open the specific build run in the CodeBuild console to jump to the associated CloudWatch log stream.

Parallel and batch builds

CodeBuild supports concurrent builds and batch builds to execute the same buildspec.yml across multiple environments or compute types (for example, ARM/x86, Linux/Windows/macOS). This is useful for matrix testing and multi-platform image builds. Each target reports success or failure so you can identify problematic configurations quickly.

A diagram titled "Executing Parallel Tests in Batch Builds" showing an AWS CodePipeline flow: a developer commits to AWS CodeCommit, CodeBuild runs, then tests run in parallel across three test groups, and results/notifications are returned to the developer.

Summary / best practices

Keep buildspec.yml in the repository root and structure phases around install, pre_build, build, and post_build.
Use the CodeBuild service role with least-privilege IAM policies required for ECR, S3, CloudWatch, and other AWS services your builds interact with.
Use caching and custom images to speed up builds and maintain consistent toolchains.
Integrate CodeBuild into CodePipeline to create multi-stage CI/CD workflows.
Monitor build logs and metrics in CloudWatch to detect and troubleshoot build issues quickly.

References and further reading:

That’s a concise introduction to CodeBuild and the buildspec file. Talk to you soon.

Introduction

Domain 1 - SDLC Automation

Domain 2 - Configuration Management and IaC

Domain 3 - Resilient Cloud Solutions

Domain 4 - Monitoring and Logging

Domain 5 - Incident and Event Response

Domain 6 - Security and Compliance

CodeBuild and the Buildspec file

Buildspec phases — the core of CodeBuild

Example `buildspec.yml`

Security: Execution role and permissions

Full CodeBuild lifecycle

Managed images and custom images

Caching

Integration with deployment and pipelines

Logs and monitoring

Parallel and batch builds

Summary / best practices

Watch Video

​Buildspec phases — the core of CodeBuild

​Example buildspec.yml

​Security: Execution role and permissions

​Full CodeBuild lifecycle

​Managed images and custom images

​Caching

​Integration with deployment and pipelines

​Logs and monitoring

​Parallel and batch builds

​Summary / best practices

Watch Video

Buildspec phases — the core of CodeBuild

Example `buildspec.yml`

Security: Execution role and permissions

Full CodeBuild lifecycle

Managed images and custom images

Caching

Integration with deployment and pipelines

Logs and monitoring

Parallel and batch builds

Summary / best practices