AWS Builder Center

Build a Production-Ready CI/CD Pipeline on AWS with GitHub Actions, Docker, and ECS

Learn how to build an automated deployment pipeline that takes code from GitHub to a Docker container running on Amazon ECS. This guide covers the architecture, AWS services, GitHub Actions workflow, security practices, and deployment strategy.

Learn how to build an automated deployment pipeline that takes code from GitHub to a Docker container running on Amazon ECS. This guide covers the architecture, AWS services, GitHub Actions workflow, security practices, and deployment strategy.
Build a Production-Ready CI/CD Pipeline on AWS with GitHub Actions, Docker, and ECS
Deploying an application manually works when a project is small. But as soon as multiple developers start pushing changes, manually building Docker images, uploading them, and restarting servers becomes slow, repetitive, and error-prone.
A better approach is to automate the entire process.
In this article, we will build a CI/CD pipeline using GitHub Actions, Docker, Amazon ECR, and Amazon ECS.
The final workflow will look like this:
Developer
|
| git push
v
GitHub Repository
|
v
GitHub Actions
|
+---- Build Application
|
+---- Run Tests
|
+---- Build Docker Image
|
v
Amazon ECR
|
v
Amazon ECS
|
v
Running Application
The goal is simple:
Push code to GitHub → automatically test, build, containerize, and deploy the application to AWS.



1. What We Are Building

Our deployment architecture will contain four major components:

GitHub

GitHub will contain our application source code and GitHub Actions workflow.

GitHub Actions

GitHub Actions will automate:
  • Installing dependencies
  • Running tests
  • Building the Docker image
  • Authenticating with AWS
  • Pushing the image to Amazon ECR
  • Deploying the new image to Amazon ECS

Amazon ECR

Amazon Elastic Container Registry (ECR) will store our Docker images.

Amazon ECS

Amazon Elastic Container Service (ECS) will run our containers.
This architecture avoids managing individual EC2 servers manually while still giving us control over the containerized application.



2. Why Use This Architecture?

A common beginner deployment looks like:
GitHub
|
v
EC2
|
v
Docker
|
v
Application
This can work, but deployment often requires manually connecting to the server and running commands.
With CI/CD:
GitHub
|
v
GitHub Actions
|
v
ECR
|
v
ECS
The deployment becomes repeatable.
This gives us several benefits:
  • Faster deployments
  • Fewer manual steps
  • Consistent deployments
  • Versioned container images
  • Easier rollback
  • Automated testing
  • Better separation between development and production



3. Prerequisites

Before starting, you should have:
  • An AWS account
  • A GitHub repository
  • Basic Git knowledge
  • Docker installed locally
  • An application that can run inside a Docker container
You should also understand basic concepts such as:
  • Docker images
  • Containers
  • IAM
  • GitHub Actions
  • AWS regions



4. Create the Dockerfile

Let's assume we have a simple Python application.
Our project structure can look like:
my-app/
│
├── app.py
├── requirements.txt
├── Dockerfile
└── .github/
└── workflows/
└── deploy.yml
A simple Dockerfile could be:
FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["python", "app.py"]
The Dockerfile describes how our application should be packaged.



5. Build and Test the Container Locally

Before introducing AWS, always test the container locally.
Build the image:
docker build -t my-app .
Run it:
docker run -p 8000:8000 my-app
If everything works locally, we can move to AWS.
This step is important because CI/CD should automate a working process—not be used to discover basic application problems.



6. Create an Amazon ECR Repository

Amazon ECR will store the Docker image.
For example, create a repository named:
my-app
After creating it, AWS provides a repository URI similar to:
ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com/my-app
The exact URI depends on your AWS account and region.



7. Create an ECS Cluster

Next, create an Amazon ECS cluster.
For a new project, AWS Fargate is a convenient option because we don't need to manage the underlying servers.
The architecture becomes:
ECS Cluster
|
v
ECS Service
|
v
Fargate Task
|
v
Docker Container
ECS manages the lifecycle of the container while Fargate handles the underlying compute infrastructure.



8. Create an ECS Task Definition

The ECS task definition tells ECS how to run our container.
It defines things such as:
  • Container image
  • CPU
  • Memory
  • Port mappings
  • Environment variables
  • IAM roles
  • Logging configuration
Conceptually:
Task Definition
│
├── CPU
├── Memory
├── Container
│ ├── Image
│ ├── Port
│ └── Environment
│
└── IAM Role
For example, our container might expose:
Port: 8000
If the application is behind an Application Load Balancer, the load balancer can forward incoming requests to the ECS service.



9. Configure IAM Permissions

This is one of the most important parts of the architecture.
Our GitHub Actions workflow needs permission to interact with AWS.
However, giving GitHub full administrator access is a bad practice.
Instead, follow the principle of least privilege.
The deployment identity should only have the permissions required for tasks such as:
Authenticate with ECR
↓
Push Docker image
↓
Update ECS service
↓
Deploy new task definition
Avoid policies such as:
AdministratorAccess
for CI/CD unless there is a specific reason and appropriate controls.



10. Use GitHub OIDC Instead of Long-Lived AWS Keys

One of the biggest improvements we can make is avoiding permanent AWS access keys inside GitHub.
Instead of storing:
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
we can use OpenID Connect (OIDC).
The authentication flow becomes:
GitHub Actions
|
| OIDC token
v
AWS IAM
|
| Temporary credentials
v
AWS Services
This means GitHub Actions can obtain temporary AWS credentials when the workflow runs.
This is significantly better than maintaining long-lived credentials in repository secrets.



11. Create the GitHub Actions Workflow

Create:
.github/workflows/deploy.yml
A simplified workflow looks like:
name: Deploy to AWS ECS

on:
push:
branches:
- main

permissions:
id-token: write
contents: read

env:
AWS_REGION: ap-south-1
ECR_REPOSITORY: my-app
ECS_SERVICE: my-app-service
ECS_CLUSTER: my-app-cluster

jobs:
deploy:
runs-on: ubuntu-latest

steps:

- name: Checkout source code
uses: actions/checkout@v4

- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
aws-region: ${{ env.AWS_REGION }}

- name: Login to Amazon ECR
id: login-ecr
uses: aws-actions/amazon-ecr-login@v2

- name: Build Docker image
run: |
docker build -t $ECR_REPOSITORY:${{ github.sha }} .

- name: Tag Docker image
run: |
docker tag \
$ECR_REPOSITORY:${{ github.sha }} \
${{ steps.login-ecr.outputs.registry }}/$ECR_REPOSITORY:${{ github.sha }}

- name: Push Docker image
run: |
docker push \
${{ steps.login-ecr.outputs.registry }}/$ECR_REPOSITORY:${{ github.sha }}

- name: Deploy to ECS
run: |
aws ecs update-service \
--cluster $ECS_CLUSTER \
--service $ECS_SERVICE \
--force-new-deployment
The exact ECS deployment configuration may differ depending on whether you use a static task definition, dynamically rendered task definitions, or another deployment strategy.



12. Why Use the Git Commit SHA as the Image Tag?

Instead of always deploying:
latest
we can tag images using the Git commit SHA:
my-app:8f31c2a
This gives us traceability.
For example:
Commit A → Image A
Commit B → Image B
Commit C → Image C
If something goes wrong with Commit C, we can identify the exact image associated with the deployment.
This is much better than having every deployment overwrite:
my-app:latest



13. Add Automated Testing

A production pipeline should not immediately deploy every piece of code that is pushed.
A better workflow is:
Push
|
v
Checkout
|
v
Install Dependencies
|
v
Run Tests
|
+---- FAIL → Stop
|
v
Build Docker Image
|
v
Push to ECR
|
v
Deploy to ECS
For example:
- name: Install dependencies
run: |
pip install -r requirements.txt

- name: Run tests
run: |
pytest
If the tests fail, the deployment should stop.
This prevents many broken builds from reaching production.



14. Improve the Pipeline Further

Once the basic pipeline works, several improvements can be added.

Security scanning

Docker images should be scanned for known vulnerabilities before deployment.
You can integrate image scanning into the CI/CD process and define policies for vulnerabilities that should block deployment.



Infrastructure as Code

Instead of manually creating AWS resources, use Infrastructure as Code.
Popular choices include:
  • Terraform
  • AWS CloudFormation
  • AWS CDK
For example:
Terraform
|
+---- VPC
+---- ECR
+---- ECS
+---- IAM
+---- Load Balancer
This makes infrastructure reproducible.



Monitoring

A deployment isn't complete just because the container starts.
You should also monitor:
  • CPU utilization
  • Memory utilization
  • Request errors
  • Application logs
  • Container restarts
  • Deployment failures
Amazon CloudWatch can be used for logs, metrics, and alarms.



15. Production Architecture

A more complete production architecture could look like this:
Internet
|
v
Application Load
Balancer
|
v
Amazon ECS
Fargate
/ \
v v
Container Container
\ /
\ /
|
v
Application
|
v
CloudWatch

Developer
|
v
GitHub
|
v
GitHub Actions
|
+---- Tests
|
+---- Docker Build
|
+---- Security Scan
|
v
Amazon ECR
|
v
Amazon ECS
This architecture provides a clean separation between source control, CI/CD, container storage, compute, and monitoring.



16. Common Mistakes to Avoid

1. Using AdministratorAccess

Don't give your CI/CD workflow unnecessary permissions.
Use least privilege.

2. Storing permanent AWS credentials

Prefer GitHub OIDC with short-lived credentials.

3. Using only  latest 

Use immutable version tags such as Git commit SHAs.

4. Skipping tests

A successful Docker build doesn't necessarily mean the application works.

5. Ignoring logs

Always configure application and container logging.

6. Deploying everything manually

If the process has to be repeated frequently, automate it.



17. What Happens After  git push ?

Once everything is configured, the deployment process becomes almost invisible to the developer.
The developer runs:
git add .
git commit -m "Add new feature"
git push origin main
GitHub detects the push.
Then:
GitHub
↓
GitHub Actions starts
↓
Tests run
↓
Docker image is built
↓
Image is tagged with commit SHA
↓
Image is pushed to ECR
↓
ECS deployment starts
↓
New container starts
↓
Application becomes available
The developer no longer needs to manually SSH into a server and execute deployment commands.
That's the real value of CI/CD.



18. Final Thoughts

CI/CD isn't simply about making deployments faster.
The bigger advantage is repeatability and reliability.
By combining GitHub Actions with AWS services, we can create a deployment pipeline where the same process happens every time:
Code
↓
Test
↓
Build
↓
Scan
↓
Package
↓
Deploy
↓
Monitor
For production systems, this foundation can be extended with automated rollbacks, blue/green deployments, infrastructure as code, security scanning, approval gates, autoscaling, and observability.
The important principle is to start simple and automate progressively.
A good deployment pipeline should make the safe path the easiest path.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article