GitHub Actions + Docker + AWS ECS CI/CD: AI-Optimized Technical Reference

Configuration Requirements

Docker Configuration That Actually Works

FROM node:18-alpine
WORKDIR /app

# Copy package files first for better caching
COPY package*.json ./
RUN npm ci --only=production && npm cache clean --force

# Copy app source
COPY . .

# Don't run as root
USER node
EXPOSE 3000
CMD ["npm", "start"]

Critical Docker Requirements:

• Multi-stage builds reduce image size from 1.5GB to 200MB but introduce dependency breakage
• npm ci --only=production breaks builds requiring TypeScript or build tools
• .dockerignore is mandatory - without it, images reach 2GB including node_modules, .git
• Multi-platform builds required: docker build --platform linux/amd64

ECS Task Definition Requirements

{
  "family": "my-app",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "256",
  "memory": "512",
  "executionRoleArn": "arn:aws:iam::account:role/ecsTaskExecutionRole",
  "containerDefinitions": [{
    "name": "my-app",
    "image": "account.dkr.ecr.region.amazonaws.com/my-app:latest",
    "portMappings": [{"containerPort": 3000}],
    "environment": [
      {"name": "PORT", "value": "3000"}
    ],
    "logConfiguration": {
      "logDriver": "awslogs",
      "options": {
        "awslogs-group": "/ecs/my-app",
        "awslogs-region": "us-east-1",
        "awslogs-stream-prefix": "ecs"
      }
    }
  }]
}

Critical ECS Specifications:

• CPU units: 256-4096 (AWS engineers hate round numbers)
• Memory: Must be specific combinations or ECS fails
• Environment variables must be strings, not numbers
• Health check endpoint is mandatory: /health

GitHub Actions OIDC Setup

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Configure AWS
      uses: aws-actions/configure-aws-credentials@v4
      with:
        role-to-assume: arn:aws:iam::${{ secrets.AWS_ACCOUNT_ID }}:role/github-actions-role
        role-session-name: GitHubActions
        aws-region: us-east-1

OIDC Trust Policy:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "Federated": "arn:aws:iam::ACCOUNT:oidc-provider/token.actions.githubusercontent.com"
    },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": {
        "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
      },
      "StringLike": {
        "token.actions.githubusercontent.com:sub": "repo:username/repo:*"
      }
    }
  }]
}

Resource Requirements and Costs

Time Investment

• Week 1: Docker builds locally, dependency conflicts
• Week 2: GitHub Actions ECR integration, OIDC debugging
• Week 3: ECS task execution, security group issues
• Week 4: Health check configuration, environment variables
• Week 5: Production deployment, database migration integration
• Week 6: Monitoring setup, false alarm resolution

Total Implementation Time: 6 weeks minimum

Cost Breakdown

• GitHub Actions: $0.008/minute - inefficient builds cost $100+/month
• ECR: $0.10/GB/month - 50 old images = $60/month without lifecycle policies
• Fargate: $0.04048/vCPU/hour - small app (0.25 vCPU) = $7.20/month
• Load Balancer: $16/month constant cost
• CloudWatch Logs: Free with 30-day retention, expensive with indefinite retention

Expertise Requirements

• Docker: Multi-stage builds, layer caching, platform differences
• AWS Networking: Security groups, subnets, NAT gateways
• ECS: Task definitions, service configuration, deployment strategies
• GitHub Actions: YAML syntax, OIDC setup, secret management

Critical Warnings and Failure Modes

Docker Build Failures

Symptom: Builds work locally, fail in CI
Root Causes:

• Different architectures (ARM vs x86)
• Missing .dockerignore
• Hard-coded paths breaking on Linux
• Dependency on local environment variables

Solution: Use --platform linux/amd64, proper .dockerignore

ECS Task Death (Exit Code 1)

Most Common Causes:

1. Port mismatch: App listens on 3000, task definition expects 80
2. Missing environment variables: DATABASE_URL undefined
3. Wrong working directory: App expects /usr/src/app, Dockerfile uses /app
4. Permission issues: Running as root locally, restricted in container

Debugging: Check CloudWatch logs, not ECS console messages

Networking Failures

Symptoms: App runs but users can't reach it
Check Order:

1. Security groups - ECS task needs outbound internet rules
2. Load balancer target groups - health check path must exist
3. Subnet routing - public subnets for ALB, private for ECS
4. NAT Gateway - private subnets need internet for outbound calls

GitHub Actions Cost Explosions

Root Causes:

• No Docker layer caching (default disabled)
• Using npm install instead of npm ci
• Rebuilding unchanged dependencies
• No node_modules caching

Build Time Reduction: 45 minutes → 3 minutes with proper caching

Database Migration Disasters

Anti-Pattern: Running migrations in app container
Consequence: "App is up but database is broken" scenarios
Solution: Separate migration task definition, run before app deployment

Decision Support Matrix

Deployment Strategies

Strategy	AWS Claims	Reality	Failure Mode	Recommendation
Rolling	"Gradual replacement"	Half traffic hits new code immediately	Health checks fail, ECS kills everything	Use unless you're Netflix
Blue-Green	"Zero downtime"	Costs 2x for 10 minutes, works perfectly	Database migrations break everything	Skip unless handling money
Canary	"Risk mitigation"	More config time than deploy time	5% users get broken experience	Only with dedicated DevOps team
Recreate	"Simple strategy"	Site down 3 minutes	Users notice, support tickets	Never use in production

Alternative Platforms

Platform	Cost	Complexity	Best For
ECS	$100+/month	High	Fine-grained control, AWS integration
Render	$7/month	Low	Side projects, "just works"
Railway	Good free tier	Low	Similar to Render
Fly.io	Moderate	Medium	Balance of control and simplicity

Recommendation: Only use ECS if you need production-grade orchestration or AWS service integration

Implementation Checklist

Initial Setup

• Create ECR repository with lifecycle policies
• Set up Fargate cluster (not EC2)
• Configure OIDC provider and IAM role
• Create task definition with proper resource limits

Docker Optimization

• Multi-stage build structure
• Proper .dockerignore file
• Platform-specific builds
• Node.js memory limits: --max-old-space-size=400

GitHub Actions Configuration

• OIDC authentication (no AWS keys in repo)
• Docker layer caching enabled
• Node modules caching
• Parallel build steps where possible

Monitoring and Alerting

• Health check endpoint: GET /health
• CloudWatch alarms: task count, CPU, memory, error rate
• Log retention set to 30 days
• Cost monitoring enabled

Security Hardening

• Run containers as non-root user
• Security groups properly configured
• No secrets in environment variables
• Regular base image updates

Breaking Points and Thresholds

Performance Limits

• UI breaks at 1000+ spans: Makes debugging large distributed transactions impossible
• Build timeout: 6 hours GitHub Actions limit with inefficient Docker builds
• Memory limits: Node.js will consume all available RAM without --max-old-space-size
• Health check failures: 30-second restart loop if endpoint doesn't respond

Cost Thresholds

• $100/month: Reasonable for production workload
• $400/month: Usually indicates misconfiguration (old images, oversized containers)
• 10 deploys/day: $3.60 per deploy with inefficient builds

Scaling Considerations

• Fargate vs EC2: 3x cost premium for Fargate worth it for mental health
• Single AZ vs Multi-AZ: Cross-AZ data transfer charges add up quickly
• Auto-scaling thresholds: CPU >80%, Memory >85% trigger scaling

Common Misconceptions

1. "ECS is like Docker Compose": ECS networking is quantum physics-level complex
2. "Fargate is expensive": Mental health cost of EC2 debugging exceeds price difference
3. "Health checks are optional": Without them, ECS restarts containers every 30 seconds
4. "GitHub Actions is cheap": Inefficient builds cost $100+/month
5. "Multi-stage builds always help": They introduce dependency management complexity

Success Criteria

Working System Indicators

• Deploy to main triggers automatic build and deployment
• Health checks pass consistently
• Application logs visible in CloudWatch
• No manual server access required
• Rollback capability through ECS service updates

Performance Benchmarks

• Build time: <5 minutes after first run
• Deployment time: <10 minutes end-to-end
• Zero downtime: Rolling deployments work without service interruption
• Cost predictability: Monthly AWS bill variance <20%