Skip to main content
This step-by-step guide shows how to configure an AWS CodeBuild project that builds a Docker image from your repository and pushes it to Amazon ECR. Follow the sequence below in the AWS Console; screenshots show the key configuration steps.
  1. Open the AWS Console and navigate to CodeBuild. If you already have projects they will be listed; otherwise create a new one.
  2. Click Create project, and give it a descriptive name. Example: AWS Microservices Project.
  3. Configure the project source. CodeBuild supports multiple source providers; in this walkthrough the source is hosted in AWS CodeCommit.
The image shows a screenshot of the AWS Console, specifically within the CodeBuild project setup where a user is selecting a source provider from a dropdown menu. Options include "No source," "Amazon S3," "AWS CodeCommit," "GitHub," "Bitbucket," and "GitHub Enterprise."
  1. Select AWS CodeCommit as the source provider. Choose the repository (example: AWS Microservice Project) and the branch to build (example: master). This tells CodeBuild which repository and branch to clone for each build.
The image shows a webpage from AWS CodeBuild where a user is configuring a build project. The source provider is AWS CodeCommit, and it includes settings for repository, branch, and environment provisioning.
  1. Scroll to the Environment section and choose an environment image that includes Docker and a modern AWS CLI (preferably AWS CLI v2). Typical defaults you can start with:
To build Docker images inside CodeBuild you must enable Privileged mode so the build can run Docker (Docker-in-Docker). Also ensure the selected environment image includes AWS CLI v2 because the example uses aws ecr get-login-password. If your image only has AWS CLI v1, either use aws ecr get-login or pick a different environment image.
  1. Configure the service role. CodeBuild will create or let you choose an IAM role for the project. Grant the role only the permissions it needs. Typical required permissions:
  1. Keep CloudWatch Logs enabled during development. Logs are extremely useful for diagnosing build failures and verifying each build phase.
The image shows an AWS console interface where a build project is being configured in AWS CodeBuild, including settings for the environment image, compute options, operating system, runtime, and service role.
  1. When you click Create project, CodeBuild will look for a build specification file. By default it expects buildspec.yml in the repository root. If this file is missing or misnamed the project will fail at build time.
  • The buildspec filename must be exactly buildspec.yml (not .yaml and check case sensitivity).
  • You can also paste a buildspec directly in the console under the Buildspec section, but versioning the file in your repo is recommended.
  1. Start a build by clicking Start build. CodeBuild will:
    • Clone the configured repository and checkout the target branch.
    • Look for buildspec.yml in the repository root.
    • Execute lifecycle phases defined in buildspec.yml (pre_build, build, post_build).
    • Emit logs to the CodeBuild console and CloudWatch Logs.
The image shows an AWS CodeBuild interface indicating the build status of a project named "aws-microservice-project", which is currently in progress. Details like the initiator, build ARN, and start time are displayed on the page.
  1. Inspect the build logs in the CodeBuild console (or CloudWatch) to verify each phase. The first logs show cloning; subsequent logs show commands executed in buildspec.yml such as ECR authentication, Docker build, tag, and push operations.
Example buildspec.yml for building and pushing a Docker image to ECR
  • Assumes the following environment variables are set in the CodeBuild project configuration (or are derivable via IAM role / metadata):
    • AWS_ACCOUNT_ID
    • AWS_DEFAULT_REGION
    • IMAGE_REPO_NAME
Troubleshooting checklist and tips:
  • Confirm buildspec.yml is present in the repository root and named exactly buildspec.yml.
  • Verify the environment image includes Docker and AWS CLI v2, or adjust ECR login commands accordingly.
  • Ensure the CodeBuild service role has ECR push and CodeCommit read permissions and can write CloudWatch logs.
  • If you want the build to create the repository automatically, add ecr:CreateRepository to the role or create the repository manually beforehand.
  • On failure, review the CodeBuild console logs and CloudWatch Logs to identify the failing phase and command.
After the build completes, check the ECR console for the new image tag and review build logs to confirm successful authentication, Docker build, tag, and push steps. Further reading and references:

Watch Video