Skip to main content
Well, now that we have set up our ECR repository, how do we actually build a Docker image programmatically? CodeBuild runs the build for us, but you need a build specification to tell CodeBuild which steps to execute.
The image features the AWS CodeBuild logo, which includes a crane graphic with code symbols and the text "AWS CodeBuild" beneath it.
When building a Docker image locally, you run commands in a terminal. For automated builds with AWS CodeBuild, you define those steps in a build specification file named buildspec.yml (or buildspec.yaml). This YAML file describes the lifecycle of the build and the commands to run in each phase.
Recommendation: Use the buildspec.yml filename (lowercase .yml) for consistency; .yaml is functionally equivalent.
The image displays the text "Buildspec.yml" and "create" with a gear icon, likely referring to creating a buildspec.yml file used in build configurations.
Below is a typical buildspec.yml for building a Docker image and pushing it to Amazon ECR. The file is organized into sections: version, env > variables, and phases (including pre_build, build, and post_build).
Summary of the main buildspec.yml sections: Phases explained:
  • pre_build: Preparation tasks such as authenticating to ECR, installing dependencies, or setting up credentials. The example uses aws ecr get-login-password to log Docker in to ECR.
  • build: Core build steps — for Docker this includes docker build and docker tag.
  • post_build: Finalization steps such as pushing the image to ECR, uploading artifacts to S3, or notifying CI/CD systems.
Common requirements and best practices when using Docker with CodeBuild:
  • Environment variables:
    • Ensure AWS_ACCOUNT_ID and AWS_DEFAULT_REGION are defined either in the CodeBuild project environment variables or replaced with literal values in the buildspec.yml. They are not injected automatically unless configured.
  • Privileged mode:
    • To execute Docker commands inside CodeBuild, enable “Privileged” mode on the build environment and use an image that includes Docker (or supports Docker-in-Docker).
  • Service role permissions:
    • The CodeBuild service role must include ECR permissions such as:
      • ecr:GetAuthorizationToken
      • ecr:BatchCheckLayerAvailability
      • ecr:PutImage
      • ecr:InitiateLayerUpload
      • ecr:UploadLayerPart
      • ecr:CompleteLayerUpload
    • Add any additional permissions required by your workflow (KMS, S3, CloudWatch Logs, etc.).
Important: Without Privileged mode enabled or the appropriate service-role IAM permissions, Docker commands and pushing to ECR will fail. Verify both the build environment settings and the IAM policy before running the build.
Example variations and tips:
  • For language-specific projects (Java, Node, Python), use pre_build to install dependencies, build to compile/package artifacts, and post_build to upload artifacts or publish releases.
  • Use environment variables to parameterize repository names and tags so a single buildspec.yml can work across environments (dev, staging, prod).
  • If you use KMS-encrypted images or private S3 artifacts, ensure the service role has access to KMS/S3 as needed.
Links and References With this buildspec.yml in your repository and a configured CodeBuild project, CodeBuild will run the defined steps and produce your Docker image in ECR automatically. That’s it for this lesson. Speak with you in the next lesson.

Watch Video