Skip to content

Zero-downtime deploys to ECS Fargate with GitHub Actions and OIDC

Ship containers to ECS without long-lived AWS keys: OIDC federation, a lean pipeline, deployment circuit breakers and health checks that actually protect you.

HSHarsh Shah2 min read

A deploy pipeline has two jobs: get new code running, and refuse to break what's already running. Most pipelines I review do the first well and the second barely at all.

Here's the setup I use for ECS Fargate services.

Step 1 — drop the access keys#

Static AWS_ACCESS_KEY_ID secrets in CI are a liability: they never expire and they leak. GitHub Actions can assume an IAM role directly through OIDC instead.

iam/github-oidc.tf
hcl
resource "aws_iam_openid_connect_provider" "github" {
  url            = "https://token.actions.githubusercontent.com"
  client_id_list = ["sts.amazonaws.com"]
}
 
data "aws_iam_policy_document" "trust" {
  statement {
    actions = ["sts:AssumeRoleWithWebIdentity"]
    principals {
      type        = "Federated"
      identifiers = [aws_iam_openid_connect_provider.github.arn]
    }
    condition {
      test     = "StringLike"
      variable = "token.actions.githubusercontent.com:sub"
      values   = ["repo:my-org/my-service:ref:refs/heads/main"]
    }
  }
}

Step 2 — the pipeline#

.github/workflows/deploy.yml
yaml
name: deploy
on:
  push:
    branches: [main]
 
permissions:
  id-token: write # required for OIDC
  contents: read
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
 
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.DEPLOY_ROLE_ARN }}
          aws-region: eu-west-1
 
      - id: ecr
        uses: aws-actions/amazon-ecr-login@v2
 
      - name: Build & push
        run: |
          IMAGE=${{ steps.ecr.outputs.registry }}/my-service:${{ github.sha }}
          docker build -t "$IMAGE" .
          docker push "$IMAGE"
          echo "image=$IMAGE" >> "$GITHUB_OUTPUT"
        id: build
 
      - name: Deploy
        run: |
          aws ecs update-service --cluster prod --service my-service \
            --force-new-deployment
          aws ecs wait services-stable --cluster prod --services my-service

Tag images with the commit SHA, never latest. It makes rollbacks a one-liner and tells you exactly what's running.

Step 3 — let ECS protect you#

Rolling deployments in ECS are safe only if the service knows what "healthy" means. Three settings matter:

SettingValueWhy
minimumHealthyPercent100Never drop below current capacity during a deploy
maximumPercent200Start the new tasks before stopping old ones
deploymentCircuitBreakerenable + rollbackAuto-revert if new tasks keep failing
ecs/service.tf
hcl
resource "aws_ecs_service" "app" {
  # ...
  deployment_minimum_healthy_percent = 100
  deployment_maximum_percent         = 200
  deployment_circuit_breaker {
    enable   = true
    rollback = true
  }
  health_check_grace_period_seconds = 30
}

What this buys you#

  • No long-lived credentials anywhere in CI.
  • Bad deploys roll themselves back before users notice.
  • Every running task maps to a commit, so debugging starts from a known state.

It's not fancy, and that's the point: boring pipelines are the ones you can trust at 5 p.m. on a Friday.

Thanks for reading. Found a mistake? Let me know.

// Keep reading