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 vGitHub Repository | vGitHub Actions | +---- Build Application | +---- Run Tests | +---- Build Docker Image | vAmazon ECR | vAmazon ECS | vRunning ApplicationThe 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 | vEC2 | vDocker | vApplicationThis can work, but deployment often requires manually connecting to the server and running commands.
With CI/CD:
GitHub | vGitHub Actions | vECR | vECSThe 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.ymlA 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-appIf 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-appAfter creating it, AWS provides a repository URI similar to:
ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com/my-appThe 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 | vECS Service | vFargate Task | vDocker ContainerECS 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 RoleFor example, our container might expose:
Port: 8000If 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 definitionAvoid policies such as:
AdministratorAccessfor 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_IDAWS_SECRET_ACCESS_KEYwe can use OpenID Connect (OIDC).
The authentication flow becomes:
GitHub Actions | | OIDC token vAWS IAM | | Temporary credentials vAWS ServicesThis 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.ymlA 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-deploymentThe 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:
latestwe can tag images using the Git commit SHA:
my-app:8f31c2aThis gives us traceability.
For example:
Commit A → Image ACommit B → Image BCommit C → Image CIf 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 | vCheckout | vInstall Dependencies | vRun Tests | +---- FAIL → Stop | vBuild Docker Image | vPush to ECR | vDeploy to ECSFor example:
- name: Install dependencies run: | pip install -r requirements.txt
- name: Run tests run: | pytestIf 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 BalancerThis 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 | vGitHub | vGitHub Actions | +---- Tests | +---- Docker Build | +---- Security Scan | vAmazon ECR | vAmazon ECSThis 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 mainGitHub 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 availableThe 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 ↓MonitorFor 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.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article