A production-grade CI/CD pipeline implementation that automatically builds, pushes, and deploys containerized applications from GitHub to Amazon ECR and EC2, demonstrating modern DevOps practices and cloud infrastructure expertise.

Live Demo: aimablem.dev — Live portfolio site deployed using this pipeline

This project implements a complete production deployment pipeline from code to cloud, focusing on containerization, automation, security, and maintainability. It represents real-world DevOps practices I've implemented for cloud-native applications.

This CI/CD pipeline automatically deploys a containerized application to AWS whenever code is pushed to the main branch, demonstrating the following capabilities:

• Automated Deployments: Code changes trigger immediate, consistent deployments
• Containerization: Applications are packaged in optimized Docker containers
• Infrastructure as Code: AWS resources provisioned and managed via Terraform
• Security: Secrets management, SSH key handling, and secure cloud access
• Monitoring: Pipeline status monitoring with failure alerts
• Troubleshooting: Systematic debugging and problem-solving for production issues

The pipeline follows a modern cloud deployment architecture:

      GitHub → GitHub Actions → Docker → ECR → EC2 → Browser
      ┌───────┐    ┌───────┐    ┌───────┐    ┌───────┐    ┌───────┐    ┌───────┐
      │GitHub │    │GitHub │    │Docker │    │Amazon │    │Amazon │    │End    │
      │Repo   │───►│Actions│───►│Build  │───►│ECR    │───►│EC2    │───►│User   │
      │       │    │CI/CD  │    │Push   │    │       │    │       │    │       │
      └───────┘    └───────┘    └───────┘    └───────┘    └───────┘    └───────┘
                       │                                      ▲
                       │                                      │
                       └──────────────SSH Connection──────────┘

Image 1: Setting up the Amazon ECR private repository

• End-to-End Automation: Push to main branch automatically triggers build and deployment
• Amazon ECR Integration: Docker images securely stored in private Elastic Container Registry
• SSH Deployment: Secure direct deployment to EC2 instances
• Container Management: Graceful container stopping, removal, and redeployment
• Environment Isolation: Separate repository secrets for credentials management
• Error Handling: Automatic recovery from failures and container restart policies
• Zero-Downtime Deployment: Application remains available during updates

Image 6: Repository secrets configuration for secure CI/CD pipeline

The first phase involved setting up the cloud infrastructure required to host the application:

1. AWS ECR Repository Creation:

   • Created a private repository in ECR for storing Docker images
   • Configured repository for image mutability
   • Set up AES-256 encryption for stored images

2. EC2 Instance Provisioning:

   • Launched EC2 instance in configured VPC
   • Applied security groups for ports 22, 80, and 443
   • Generated and configured SSH key pair for secure access

3. Docker Environment Configuration:

   • Installed Docker on EC2 instance
   • Created Docker network for container isolation
   • Configured container restart policies for reliability

The second phase involved setting up the automated pipeline:

1. GitHub Repository Configuration:

   • Created .github/workflows directory for workflow files
   • Set up repository secrets for AWS credentials
   • Configured branch protection rules for main

2. GitHub Actions Workflow:

   • Created deploy.yml defining the CI/CD process
   • Implemented staged pipeline with checkpoints
   • Added error handling and failure notifications

3. Docker Image Optimization:

   • Implemented multi-stage Docker build
   • Minimized image size by excluding build dependencies
   • Configured layer caching to speed up builds

The final phase involved automating the deployment process:

1. SSH Deployment Scripts:

   • Created secure SSH connection from GitHub Actions to EC2
   • Implemented container management scripts
   • Added automatic container cleanup and garbage collection

2. Monitoring and Logging:

   • Set up pipeline status monitoring
   • Implemented container logs collection
   • Added deployment status notifications

3. Security Hardening:

   • Secured all credentials in GitHub Secrets
   • Implemented least privilege principle for AWS roles
   • Configured private network for container communication

The core of this project is the GitHub Actions workflow file, which orchestrates the entire CI/CD process:

Image 7: GitHub Actions workflow YAML file in VS Code

name: Deploy My Cloud Portfolio to AWS EC2 Instance

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{secrets.AWS_ACCESS_KEY_ID}}
          aws-secret-access-key: ${{secrets.AWS_SECRET_ACCESS_KEY}}
          aws-region: ${{secrets.AWS_REGION}}

      - name: Login to Amazon ECR
        run: |
          aws ecr get-login-password --region ${{secrets.AWS_REGION}} | docker login --username AWS --password-stdin ${{secrets.ECR_REGISTRY}}

      - name: Build Docker Image
        run: |
          docker build -t ${{secrets.ECR_REGISTRY}}/${{secrets.ECR_REPOSITORY}}:latest .

      - name: Push Docker Image to ECR
        run: |
          docker push ${{secrets.ECR_REGISTRY}}/${{secrets.ECR_REPOSITORY}}:latest

      - name: SSH into EC2 and Deploy New Container
        uses: appleboy/ssh-action@v0.1.7
        with:
          host: ${{secrets.EC2_PUBLIC_IP}}
          username: ubuntu
          key: ${{secrets.EC2_SSH_PRIVATE_KEY}}
          script: |
            aws ecr get-login-password --region ${{secrets.AWS_REGION}} | docker login --username AWS --password-stdin ${{secrets.ECR_REGISTRY}}
            docker pull ${{secrets.ECR_REGISTRY}}/${{secrets.ECR_REPOSITORY}}:latest
            docker stop portfolio-container || true
            docker rm portfolio-container || true
            docker network create app-network || true
            docker run -d --name portfolio-container --restart unless-stopped -p 3000:80 ${{secrets.ECR_REGISTRY}}/${{secrets.ECR_REPOSITORY}}:latest
            docker network connect app-network portfolio-container

Image 9: GitHub Actions workflow runs history showing testing iterations

This workflow:

1. Triggers on pushes to the main branch
2. Sets up AWS credentials for ECR access
3. Logs into Amazon ECR
4. Builds the Docker image from project files
5. Pushes the image to ECR
6. Connects to EC2 via SSH
7. Pulls the new image and deploys it as a container

The pipeline relies on several GitHub Secrets for secure credential management:

Throughout this project, I encountered and systematically resolved several technical challenges:

Problem: GitHub Actions pipeline failed during ECR authentication with errors like "name unknown: The repository does not exist"

Image 5: GitHub Actions failure showing repository name error

Root Cause: Incorrectly formatted ECR registry and repository secrets with extra slashes and spaces.

Solution: Reconstructed the ECR URL and repository name correctly, ensuring proper secret formatting:

ECR_REGISTRY = 054037110265.dkr.ecr.us-east-1.amazonaws.com
ECR_REPOSITORY = portfolio

Image 3: Successfully created ECR repository with correct naming

Problem: SSH connection to EC2 failed with "ssh.ParsePrivateKey: ssh: no key found"

Image 4: GitHub Actions failure showing SSH key parse error

Root Cause: Incomplete PEM key in GitHub Secrets, missing BEGIN/END headers.

Solution: Re-created the SSH key secret with the complete key including headers:

-----BEGIN RSA PRIVATE KEY-----
(key content)
-----END RSA PRIVATE KEY-----

Problem: After successful SSH, the EC2 instance failed to pull images from ECR with "Unable to locate credentials"

Image 2: EC2 instance terminal showing Docker commands and AWS configuration

Root Cause: AWS credentials not configured on the EC2 instance itself.

Solution:

1. Manual SSH into EC2 instance
2. Configured AWS CLI with aws configure
3. Added ECR login to deployment script
4. Verified credentials by testing ECR connection

Image 10: Successfully pushed Docker images in the ECR repository

Problem: Docker images built locally on my M1 Mac (ARM64) would not run on EC2 (AMD64)

Root Cause: Architecture mismatch between build and deployment environments.

Solution: Modified the workflow to build for the correct platform:

- name: Build Docker Image
  run: |
    docker build --platform linux/amd64 -t ${{secrets.ECR_REGISTRY}}/${{secrets.ECR_REPOSITORY}}:latest .

Image 12: SSH deployment log showing successful container operations

The implementation of this CI/CD pipeline resulted in significant improvements:

This project provided several important learning opportunities:

1. Secret Management Precision: Meticulously format and verify secret values, as even invisible characters can cause failures.

2. Infrastructure Knowledge: Understanding AWS-specific authentication flows is crucial when connecting services like GitHub Actions to ECR.

3. Container Networking: Docker networking requires special attention when deploying containerized applications.

4. Error Logging: Comprehensive logging with contextual information drastically reduces debugging time.

5. SSH Authentication: SSH key management requires careful attention to formatting and permissions.

The following improvements are planned for this pipeline:

1. Blue-Green Deployment: Implement zero-downtime deployments with traffic switching
2. Auto-Scaling: Add EC2 Auto Scaling Group for high availability
3. Automated Testing: Integrate unit and integration tests into the pipeline
4. Slack Notifications: Add deployment status notifications
5. AWS IAM Roles: Replace AWS key/secret with IAM role-based authentication
6. Monitoring Dashboard: Add CloudWatch metrics and alerts

To use this pipeline for your own projects:

• AWS Account
• GitHub Repository
• Docker installed locally
• Basic understanding of CI/CD concepts

1. Create ECR Repository:

   aws ecr create-repository --repository-name your-repo-name

2. Configure EC2 Instance:

   # Install Docker
   sudo apt update
   sudo apt install -y docker.io
   sudo systemctl enable --now docker
   
   # Create Docker network
   docker network create app-network

3. Set Up GitHub Secrets:

   • Add all required secrets mentioned in the Secrets Management section
   • Ensure SSH key is complete with BEGIN/END headers

4. Create Workflow File:

   • Create .github/workflows/deploy.yml in your repository
   • Copy the workflow file from this project, adjusting as needed

5. Test Pipeline:

   • Push to main branch
   • Monitor GitHub Actions tab for build status
   • Verify deployment on EC2 instance

After resolving all the challenges, the pipeline successfully deploys the application to production:

Image 11: Successful GitHub Actions deployment showing all steps completed

Image 8: The live portfolio website deployed at aimablem.dev

Image 12: Adding Terraform folders to version control for infrastructure as code

This project is licensed under the MIT License - see the LICENSE file for details.

• Name: Aimable M.
• LinkedIn: linkedin.com/in/aimable-m-920608107
• GitHub: github.com/aimablM
• Website: aimablem.dev