How to Deploy a Container to AWS ECS from GitHub Actions

An ECS deploy is build, push to ECR, render a task definition, then update the service.

Authenticate to AWS via OIDC, push the image to ECR, inject the new image into the task definition, and deploy it to the service.

Steps

Configure AWS credentials via aws-actions/configure-aws-credentials and OIDC.
Log in to ECR, build and push the tagged image.
Render the task definition with the new image and deploy to the ECS service.

Workflow

.github/workflows/deploy.yml

permissions:
  id-token: write
  contents: read
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: us-east-1
      - id: ecr
        uses: aws-actions/amazon-ecr-login@v2
      - run: |
          docker build -t ${{ steps.ecr.outputs.registry }}/app:${{ github.sha }} .
          docker push ${{ steps.ecr.outputs.registry }}/app:${{ github.sha }}
      - id: task
        uses: aws-actions/amazon-ecs-render-task-definition@v1
        with:
          task-definition: task-def.json
          container-name: app
          image: ${{ steps.ecr.outputs.registry }}/app:${{ github.sha }}
      - uses: aws-actions/amazon-ecs-deploy-task-definition@v2
        with:
          task-definition: ${{ steps.task.outputs.task-definition }}
          service: app-service
          cluster: prod
          wait-for-service-stability: true

Gotchas

Tag images with the commit SHA so rollbacks point at a real image.
Latchkey runs these deploys on cheaper managed runners that self-heal transient ECR or AWS errors.

How to Deploy a Container to AWS ECS from GitHub Actions

Steps

Workflow

Gotchas

Related guides