GitHub Actions + Docker + ECS: Stop SSH-ing Into Servers Like It's 2015

Look, the idea is simple: push to main, magic happens, your app runs in production. Reality is messier.

The Happy Path That Never Happens

You push code. GitHub Actions kicks off a workflow. Docker builds your image. ECR stores it. ECS deploys it. Your users are happy. You sleep through the night.

Here's what actually happens when you first set this up:

Week 1: Your Docker build fails because you forgot to add node_modules to .dockerignore and your image is 2GB. GitHub Actions times out after 6 hours trying to push it.

Week 2: Build works, but your ECS task dies immediately with exit code 1. The logs show "Error: Cannot find module 'express'" because your multi-stage build is too clever and deleted the wrong dependencies.

Week 3: App runs but can't connect to the database. Your task definition has the wrong security group. You spend 4 hours learning that ECS networking is about as intuitive as quantum physics.

Docker: The Part That Should Be Easy But Isn't

Multi-stage builds are great in theory. They reduce image size from 1.5GB to 200MB. They also introduce a dozen new ways to break your dependencies.

## This looks clean but will bite you
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

## Your app works locally but breaks here
FROM node:18-alpine AS production  
COPY --from=builder /app/node_modules ./node_modules
COPY . .
CMD ["npm", "start"]

Pro tip: `npm ci --only=production` doesn't install devDependencies, which breaks builds that need TypeScript or other build tools. You'll discover this at 11pm when your supposedly "production-ready" image crashes because TypeScript isn't installed.

ECS: Where Your Deployment Goes to Die

ECS task definitions are XML-level verbose. A simple Node.js app needs 150+ lines of JSON to define CPU (256-4096 units, because apparently AWS engineers hate round numbers), memory (must be specific combinations or ECS throws a tantrum), and networking (good luck).

Real talk: Fargate costs 3x more than EC2 but saves your sanity. You'll pay the premium after spending a weekend debugging why your container can't resolve DNS on a custom EC2 cluster.

GitHub Actions: The Good News

The only part of this stack that doesn't hate you. Actions for AWS are actually well-maintained. OIDC authentication works. The official actions don't randomly break.

But here's what nobody tells you: your first workflow will take 45 minutes to run because Docker layer caching is disabled by default and you're rebuilding everything from scratch every time.

Where The Money Goes

GitHub Actions charges $0.008/minute. Sounds cheap until you realize your inefficient Docker builds consume 15 minutes per deployment. That's $3.60 per deploy. Deploy 10 times a day and suddenly you're paying $100+ monthly just for CI.

ECR costs sneak up on you. $0.10/GB/month sounds reasonable until you accumulate 50 old images because you didn't set up lifecycle policies. Your "free" container registry costs $60/month.

Fargate pricing is $0.04048/vCPU/hour. A small app (0.25 vCPU, 512MB RAM) costs $7.20/month if it runs 24/7. Scale to handle real traffic and you're looking at $100+/month just for compute.

The Real Architecture

Here's what actually happens in production:

1. Developer pushes to main at 5:47pm on Friday (why do we do this to ourselves?)
2. GitHub Actions starts. Build time: 12 minutes because someone added a 500MB dependency
3. ECR image scan finds 47 "critical" vulnerabilities in base OS packages you can't control
4. Deployment succeeds but health checks fail. Task keeps restarting
5. You debug for 2 hours, discover the container port is 3000 but load balancer expects 80
6. Fix that, redeploy. Health checks pass but users get 500 errors
7. Turns out your database connection string is wrong. Environment variable was DATABASE_URL, your code expects DB_URL
8. By 8:30pm everything works. You promise yourself you'll never deploy on Friday again
9. You deploy on Friday again next week

The good news? Once it works, it really works. The bad news? Getting there requires sacrificing several weekends to the AWS documentation gods.

Skip the AWS console. Seriously. Use Terraform or you'll be clicking through 47 different screens every time you need to change a CPU limit. Here's what actually works after you've debugged everything twice.

Start With ECR Because That's Easy

Create your ECR repo and enable image scanning. The scanning will find 200 vulnerabilities in your base image, 199 of which you can't fix because they're in Ubuntu packages. You'll learn to ignore them.

## This works, unlike half the AWS CLI examples
aws ecr create-repository --repository-name my-app --image-scanning-configuration scanOnPush=true
aws ecr put-lifecycle-policy --repository-name my-app --lifecycle-policy-text file://lifecycle.json

Set up lifecycle policies immediately or your ECR bill will be $200 next month because you kept every single build image.

ECS Cluster Setup (The Part That Will Frustrate You)

Create a Fargate cluster. Don't use EC2 unless you enjoy troubleshooting networking at midnight. Fargate costs more but your mental health is worth it.

Task definitions are where AWS decided to make developers suffer. A simple Node.js app requires 150 lines of JSON. Here's the minimal version that actually works:

{
  "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}],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/my-app",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}

Notice how the memory is in MB but CPU is in "units"? AWS engineers apparently hate consistency.

The GitHub Action That Actually Deploys

Forget the marketplace actions that half-work. Here's a workflow that handles the edge cases:

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
    
    - name: Login to ECR
      run: |
        aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin ${{ secrets.AWS_ACCOUNT_ID }}.dkr.ecr.us-east-1.amazonaws.com
    
    - name: Build and push
      run: |
        docker build -t my-app:${{ github.sha }} .
        docker tag my-app:${{ github.sha }} ${{ secrets.AWS_ACCOUNT_ID }}.dkr.ecr.us-east-1.amazonaws.com/my-app:${{ github.sha }}
        docker tag my-app:${{ github.sha }} ${{ secrets.AWS_ACCOUNT_ID }}.dkr.ecr.us-east-1.amazonaws.com/my-app:latest
        docker push ${{ secrets.AWS_ACCOUNT_ID }}.dkr.ecr.us-east-1.amazonaws.com/my-app:${{ github.sha }}
        docker push ${{ secrets.AWS_ACCOUNT_ID }}.dkr.ecr.us-east-1.amazonaws.com/my-app:latest
    
    - name: Update ECS service
      run: |
        aws ecs update-service --cluster my-cluster --service my-service --force-new-deployment --region us-east-1

Docker Builds That Don't Suck

Your Dockerfile probably looks like this and takes 15 minutes to build:

FROM node:18
WORKDIR /app
COPY . .
RUN npm install
CMD ["npm", "start"]

Here's one that builds in 3 minutes after the first run:

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"]

Add a .dockerignore file or your image will be 2GB because you included node_modules, .git, and your entire download folder:

node_modules
.git
*.log
.DS_Store
coverage/
.nyc_output/

OIDC Setup (Do This Once, Correctly)

OIDC eliminates AWS keys in your repo. Set it up in AWS IAM:

{
  "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:yourusername/yourrepo:*"
        }
      }
    }
  ]
}

Get this wrong and you'll get cryptic "AssumeRole failed" errors that take 3 hours to debug.

The Gotchas That Will Ruin Your Day

Health checks are not optional. ECS will restart your container every 30 seconds if health checks fail. Add this to your Express app:

app.get('/health', (req, res) => res.status(200).send('OK'));

Environment variables aren't strings in task definitions. This will break:

"environment": [
  {"name": "PORT", "value": 3000}  // Wrong! Must be string
]

This works:

"environment": [
  {"name": "PORT", "value": "3000"}  // String, not number
]

Security groups matter. Your container can't reach the internet if the security group blocks outbound traffic. Learn this the hard way when your app can't connect to external APIs.

Resource limits are enforced. Set your Node.js max memory or it'll use all available RAM and get killed by ECS:

process.env.NODE_OPTIONS = '--max-old-space-size=400';

Deployment Strategies That Work

Rolling deployments are fine for most apps. Don't overcomplicate with blue-green unless you're running a bank.

Set your deployment configuration to:

• Maximum percent: 200% (allows new tasks before killing old ones)
• Minimum healthy percent: 100% (ensures zero downtime)
• Health check grace period: 300 seconds (your app needs time to start)

Monitoring That Matters

CloudWatch Logs are included. Set up log aggregation or you'll be grep-ing through individual log streams like a caveman.

Create CloudWatch alarms for:

• Task count drops below desired (your app crashed)
• CPU above 80% (time to scale)
• Memory above 85% (about to get killed)
• Error rate above 5% (something's broken)

Skip fancy monitoring until you have the basics working. You'll have plenty of real errors to debug first.

Timeline: How Long This Really Takes

• Week 1: Get Docker building locally. Fight with dependencies.
• Week 2: Get GitHub Actions pushing to ECR. Debug OIDC permissions.
• Week 3: Get ECS task running. Discover security group issues.
• Week 4: Get health checks passing. Fix environment variables.
• Week 5: Production deploy works. Realize you forgot about database migrations.
• Week 6: Add monitoring. Get paged at 2am because of false alarms.

Budget 6 weeks minimum. Anyone who says they did it in a day either had help or is lying.