> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CodeBuild and the Buildspec file

> Overview of AWS CodeBuild and how buildspec.yml defines install, pre_build, build, and post_build phases, plus security, caching, images, and CI/CD integration

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.](https://mintcdn.com/kodekloud-c4ac6d9a/Kx09awxrzT0QVPGP/images/AWS-Certified-DevOps-Engineer-Professional/Domain-1-SDLC-Automation/CodeBuild-and-the-Buildspec-file/aws-ci-codecommit-codebuild-s3-cloudwatch.jpg?fit=max\&auto=format\&n=Kx09awxrzT0QVPGP\&q=85\&s=b040b2df273b28dc237f785b57b959b2)

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.](https://mintcdn.com/kodekloud-c4ac6d9a/Kx09awxrzT0QVPGP/images/AWS-Certified-DevOps-Engineer-Professional/Domain-1-SDLC-Automation/CodeBuild-and-the-Buildspec-file/codebuild-ci-build-env-aws-parallel.jpg?fit=max\&auto=format\&n=Kx09awxrzT0QVPGP\&q=85\&s=e85608c89bcf0b28e7d64cd154e75cdc)

## 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.](https://mintcdn.com/kodekloud-c4ac6d9a/Kx09awxrzT0QVPGP/images/AWS-Certified-DevOps-Engineer-Professional/Domain-1-SDLC-Automation/CodeBuild-and-the-Buildspec-file/buildspec-install-prebuild-build-postbuild.jpg?fit=max\&auto=format\&n=Kx09awxrzT0QVPGP\&q=85\&s=36d1c9db90f0a24dd7f835bfd78e6fd2)

### 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).

```yaml theme={null}
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.](https://mintcdn.com/kodekloud-c4ac6d9a/Kx09awxrzT0QVPGP/images/AWS-Certified-DevOps-Engineer-Professional/Domain-1-SDLC-Automation/CodeBuild-and-the-Buildspec-file/codebuild-security-iam-roles.jpg?fit=max\&auto=format\&n=Kx09awxrzT0QVPGP\&q=85\&s=59d78ff13c068d4124a4628004c0e82d)

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.](https://mintcdn.com/kodekloud-c4ac6d9a/Kx09awxrzT0QVPGP/images/AWS-Certified-DevOps-Engineer-Professional/Domain-1-SDLC-Automation/CodeBuild-and-the-Buildspec-file/codebuild-lifecycle-flowchart.jpg?fit=max\&auto=format\&n=Kx09awxrzT0QVPGP\&q=85\&s=4b09299ee3fcd1c8d55b7c2202630012)

## 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.](https://mintcdn.com/kodekloud-c4ac6d9a/Kx09awxrzT0QVPGP/images/AWS-Certified-DevOps-Engineer-Professional/Domain-1-SDLC-Automation/CodeBuild-and-the-Buildspec-file/aws-codebuild-image-settings-ec2-lambda.jpg?fit=max\&auto=format\&n=Kx09awxrzT0QVPGP\&q=85\&s=558793d3f636da4dd7f1d643eb786775)

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.](https://mintcdn.com/kodekloud-c4ac6d9a/Kx09awxrzT0QVPGP/images/AWS-Certified-DevOps-Engineer-Professional/Domain-1-SDLC-Automation/CodeBuild-and-the-Buildspec-file/codebuild-local-cache-settings.jpg?fit=max\&auto=format\&n=Kx09awxrzT0QVPGP\&q=85\&s=3be1a8b25d896eba0485039800d0d2e8)

## 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.](https://mintcdn.com/kodekloud-c4ac6d9a/Kx09awxrzT0QVPGP/images/AWS-Certified-DevOps-Engineer-Professional/Domain-1-SDLC-Automation/CodeBuild-and-the-Buildspec-file/aws-codepipeline-codecommit-codebuild-codedeploy-qa.jpg?fit=max\&auto=format\&n=Kx09awxrzT0QVPGP\&q=85\&s=c8dd6f940a77ad4e55f90f439faf04ba)

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.

![A workflow diagram titled "CodeBuild Logs and Monitoring" showing a developer pushing code to AWS CodeCommit, which triggers AWS CodeBuild and streams logs to AWS CloudWatch.](https://mintcdn.com/kodekloud-c4ac6d9a/Kx09awxrzT0QVPGP/images/AWS-Certified-DevOps-Engineer-Professional/Domain-1-SDLC-Automation/CodeBuild-and-the-Buildspec-file/codecommit-codebuild-cloudwatch-logs-workflow.jpg?fit=max\&auto=format\&n=Kx09awxrzT0QVPGP\&q=85\&s=9730b01e2a59d8bf4b93890acf28a691)

## 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.](https://mintcdn.com/kodekloud-c4ac6d9a/Kx09awxrzT0QVPGP/images/AWS-Certified-DevOps-Engineer-Professional/Domain-1-SDLC-Automation/CodeBuild-and-the-Buildspec-file/codepipeline-parallel-tests-batch-builds-diagram.jpg?fit=max\&auto=format\&n=Kx09awxrzT0QVPGP\&q=85\&s=20b6b15a062c30539cd6361b61a10973)

## 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:

* [AWS CodeBuild Documentation](https://docs.aws.amazon.com/codebuild/latest/userguide/welcome.html)
* [Buildspec Reference](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html)
* [Amazon ECR Authentication with the CLI](https://docs.aws.amazon.com/AmazonECR/latest/userguide/Registries.html)

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

> **[Watch Video](https://learn.kodekloud.com/user/courses/aws-certified-devops-engineer-professional/module/199ecdf9-a58f-4c2d-b9c9-eac36de111cd/lesson/93187ed5-cbd5-4fd5-9227-fb5c8e8401ee)**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.