Amazon ECS CI/CD Pipeline with CodePipeline, CodeBuild, and ECR

What is an ECS CI/CD pipeline?

Think of it as an automated assembly line for your Docker container. Every time a developer pushes code, the line starts moving: the image gets built, tested, stored in ECR, and shipped to the ECS service running in production. No manual steps, no SSH-ing into servers.

Three AWS services split the work: CodePipeline is the coordinator that moves work through stages and passes files between them. CodeBuild is the builder that runs your tests, builds the Docker image, and pushes it to ECR. The ECS deploy action (or CodeDeploy for blue/green) is the deployer that updates the running service to use the new image.

How an Amazon ECS CI/CD pipeline works

Here is what happens from the moment a developer pushes code to the moment users see the new version:

1. Code push. A developer pushes a commit to the main branch of the source repository (GitHub, CodeCommit, or Bitbucket via CodeStar Connections).
2. Source trigger. CodePipeline detects the push and starts the pipeline automatically. The source stage downloads the repository and packages it as the first artifact.
3. Build and test. CodeBuild picks up the source artifact, runs tests, and builds a Docker image. See building Docker images with CodeBuild for the full build process.
4. Image push to ECR. CodeBuild pushes the new image to Amazon ECR tagged with the git commit SHA. Every build produces a uniquely tagged, immutable image. See ECR best practices for tag strategies and lifecycle policies.
5. Artifact generation. CodeBuild writes an artifact file (imagedefinitions.json for rolling update, or imageDetail.json for blue/green) that tells the deploy stage exactly which image to use. This file is the bridge between Build and Deploy.
6. Deployment to ECS. The deploy stage reads the artifact file and updates the ECS service. Rolling update replaces old tasks gradually. Blue/green via CodeDeploy creates a new task set and shifts ALB traffic to it.
7. Health checks. ECS verifies that new tasks start and pass health checks before marking them healthy. For blue/green, CodeDeploy waits for all green tasks to pass before shifting any traffic. If health checks fail, the deployment stops.
8. Rollback path. For rolling updates, rollback means manually re-deploying the previous task definition revision. For blue/green, rollback is instant: CodeDeploy shifts traffic back to the still-running blue task set. See rollbacks in CodeDeploy for configuration options.

Prerequisites

Before building the pipeline, the following resources must already exist:

• ECS cluster and service. The ECS service must exist with a task definition that references your container. The pipeline updates the task definition; it does not create the service from scratch.
• ECR repository. CodeBuild needs a private ECR repository to push the Docker image to. See ECR best practices for repository setup and lifecycle policies that prevent unbounded image accumulation.
• Source repository. GitHub, CodeCommit, or another source provider connected to CodePipeline via a CodeStar Connections connection.
• IAM roles. Three separate roles are needed: one for CodePipeline (permission to invoke CodeBuild and access S3), one for CodeBuild (permission to push to ECR and write CloudWatch Logs), and the ECS task execution role (permission to pull from ECR at task start time).
• S3 artifact bucket. CodePipeline stores pipeline artifacts in S3. The console creates this automatically, or you can specify an existing bucket.
• ALB with two target groups (blue/green only). Blue/green deployments require an Application Load Balancer with two target groups registered to the ECS service. CodeDeploy shifts traffic between them. Rolling update does not require a load balancer.
• CodeDeploy application and deployment group (blue/green only). See AWS CodeDeploy overview for setup instructions.

Pipeline architecture overview

A minimal ECS CI/CD pipeline has three stages: Source, Build, and Deploy. Each stage passes artifacts (files one stage produces for the next stage to consume) along the chain. A production-ready pipeline adds a staging deploy and a manual approval gate before production.

┌──────────────────────────────────────────────────────────────┐
│  Source Stage                                                │
│  GitHub / CodeCommit / Bitbucket (push to main)             │
│  Output: source_output (source archive)                     │
└─────────────────────────┬────────────────────────────────────┘
                          ↓
┌──────────────────────────────────────────────────────────────┐
│  Build Stage (CodeBuild)                                     │
│  - Runs tests                                                │
│  - Builds Docker image                                       │
│  - Pushes image to ECR with commit SHA tag                   │
│  - Writes imagedefinitions.json (or imageDetail.json)        │
│  Output: build_output (artifact file)                       │
└─────────────────────────┬────────────────────────────────────┘
                          ↓
┌──────────────────────────────────────────────────────────────┐
│  [Recommended] Staging Deploy Stage                          │
│  Deploy to a staging ECS cluster using build_output         │
└─────────────────────────┬────────────────────────────────────┘
                          ↓
┌──────────────────────────────────────────────────────────────┐
│  [Recommended] Manual Approval Stage                         │
│  Pipeline pauses; a reviewer approves before prod continues  │
└─────────────────────────┬────────────────────────────────────┘
                          ↓
┌──────────────────────────────────────────────────────────────┐
│  Production Deploy Stage                                     │
│  Option A: ECS rolling update (simpler)                     │
│  Option B: ECS blue/green via CodeDeploy (safer)            │
└──────────────────────────────────────────────────────────────┘

The artifact file is the critical handoff between Build and Deploy. It carries the exact image URI that was just pushed to ECR so the deploy action knows which version to run.

Minimal pipeline vs production-ready pipeline

A three-stage pipeline that deploys straight to production works fine for demos and internal tools. For a service with real user traffic, several failure modes are left unhandled. Here is the difference:

For guidance on multi-environment pipeline design, see managing environments in CI/CD and dev vs staging vs production.

Required deployment artifacts

The artifact file is what the Build stage hands off to the Deploy stage. Which file you need depends on which deploy action you are using.

imagedefinitions.json — ECS rolling update

Used by the standard ECS deploy action (no CodeDeploy involved). It is a JSON array that maps container names to image URIs. The container name must exactly match the container name in your ECS task definition. A case difference or typo causes the deploy to fail or silently use the wrong image.

[
  {
    "name": "my-app",
    "imageUri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:abc12345"
  }
]

For task definitions with multiple containers, include an entry for each container you want to update. The filename is configurable in the ECS deploy action (the default is imagedefinitions.json).

imageDetail.json — ECS blue/green via CodeDeploy

Used by the CodeDeploy deploy action for ECS blue/green deployments. It contains only the image URI; the container name mapping comes from appspec.yml. This file can be written by CodeBuild in the post_build phase, or produced automatically by an Amazon ECR source action when ECR is configured as the pipeline trigger.

{
  "ImageURI": "123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:abc12345"
}

appspec.yml — ECS blue/green via CodeDeploy

Also required for CodeDeploy blue/green. This file tells CodeDeploy which task definition to deploy, which container and port to register with the load balancer, and which Lambda functions to run for pre- and post-traffic validation. See AWS CodeDeploy overview for the full appspec.yml structure and lifecycle hooks.

# appspec.yml for ECS blue/green
version: 0.0
Resources:
  - TargetService:
      Type: AWS::ECS::Service
      Properties:
        TaskDefinition: <TASK_DEFINITION>
        LoadBalancerInfo:
          ContainerName: "my-app"
          ContainerPort: 8080
Hooks:
  - BeforeAllowTraffic: "ValidateBeforeTrafficShift"
  - AfterAllowTraffic: "ValidateAfterTrafficShift"

The BeforeAllowTraffic and AfterAllowTraffic hooks point to Lambda functions that run health checks. If either Lambda fails, CodeDeploy rolls back automatically. Traffic stays on the original blue task set.

The CodeBuild buildspec for ECS

This buildspec handles the full build stage: authenticating to ECR, building the image, pushing it, and generating the imagedefinitions.json artifact for a rolling update pipeline. For the CodeBuild fundamentals behind this file, see AWS CodeBuild overview.

version: 0.2

env:
  variables:
    AWS_DEFAULT_REGION: "us-east-1"
    ECR_REPO_NAME: "my-app"
    CONTAINER_NAME: "my-app"

phases:
  pre_build:
    commands:
      - AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
      - ECR_REGISTRY="${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_DEFAULT_REGION}.amazonaws.com"
      - IMAGE_URI="${ECR_REGISTRY}/${ECR_REPO_NAME}"
      - COMMIT_HASH=$(echo $CODEBUILD_RESOLVED_SOURCE_VERSION | cut -c 1-8)
      - aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $ECR_REGISTRY

  build:
    commands:
      - docker build -t $IMAGE_URI:$COMMIT_HASH .

  post_build:
    commands:
      - docker push $IMAGE_URI:$COMMIT_HASH
      - printf '[{"name":"%s","imageUri":"%s"}]' $CONTAINER_NAME $IMAGE_URI:$COMMIT_HASH > imagedefinitions.json

artifacts:
  files:
    - imagedefinitions.json

This buildspec pushes only the commit-SHA tag, not :latest. Every deployment is traceable to an exact commit. The artifacts block tells CodePipeline to pass imagedefinitions.json to the next stage as the build_output artifact.

Deployment options: rolling update vs blue/green

Both options get your new image into production. They differ in how much control you have over the traffic shift and how quickly you can undo a bad deploy.

For a deep look at the blue/green strategy including task sets, target groups, and traffic shift configs, see blue/green deployments in AWS. For the mechanics of triggering deploys from CodeBuild output, see deploying with CodeBuild.

When to use an ECS CI/CD pipeline

• Containerized APIs on ECS. Any REST or GraphQL API running in ECS benefits from an automated pipeline. It eliminates manual image pushes and reduces human error on every release.
• Microservices architectures. When you have multiple independent ECS services, each service gets its own pipeline. A change to one service does not block others from deploying.
• Small teams that need production-grade delivery without ops overhead. CodePipeline and CodeBuild are fully managed — no Jenkins server to maintain. A small team can have a working pipeline running in an afternoon.
• Regulated or audited environments. CodePipeline generates an execution history of every pipeline run — which artifact was deployed, when, and who approved it. This is directly useful for SOC 2, PCI, and similar compliance requirements.
• Teams migrating off manual deployments. Even a minimal three-stage pipeline eliminates the most common manual-deploy errors: wrong branch deployed, stale image used, build step skipped.

Production checklist

Before using this pipeline for a service with real user traffic:

• Images are tagged with the git commit SHA, not only :latest
• Unit and integration tests run in CodeBuild before the image is pushed to ECR
• The pipeline deploys to a staging environment before production
• A manual approval action gates the production deploy
• Deployment uses blue/green with CodeDeploy, or has a documented rollback procedure for rolling update
• Health check hooks or CloudWatch alarms validate the deployment and trigger rollback on failure
• Secrets are sourced from Secrets Manager or Parameter Store, not hardcoded in buildspec
• ECR lifecycle policies are configured to clean up old images and prevent unbounded storage growth
• Pipeline IAM roles follow least privilege — each role has only the permissions it needs
• CodeBuild logs are retained in CloudWatch Logs with an appropriate retention policy