AWS CloudFormation Task ECS Deploy with GitHub Actions

Comprehensive skill for deploying ECS containers using GitHub Actions CI/CD pipelines with CloudFormation infrastructure management.

Overview

Deploy containerized applications to Amazon ECS using GitHub Actions workflows. This skill covers the complete deployment pipeline: authentication with AWS (OIDC recommended), building Docker images, pushing to Amazon ECR, updating task definitions, and deploying ECS services. Integrate with CloudFormation for infrastructure-as-code management and implement production-grade deployment strategies.

When to Use

• Deploying Docker containers to Amazon ECS with GitHub Actions
• Setting up CI/CD pipelines for ECS using CloudFormation
• Configuring AWS OIDC authentication for GitHub Actions
• Building Docker images and pushing to Amazon ECR
• Updating ECS task definitions dynamically in CI/CD
• Implementing blue/green or rolling deployments for ECS
• Managing CloudFormation stacks from GitHub Actions

Instructions

Follow these steps to set up ECS deployment with GitHub Actions:

1. Configure AWS Authentication: Set up OIDC provider for GitHub Actions
2. Create IAM Roles: Define roles for deployment actions
3. Set Up ECR Repository: Create repository with image scanning
4. Create ECS Cluster: Define cluster infrastructure
5. Configure Task Definition: Set up task and container definitions
6. Set Up ECS Service: Configure service with deployment strategy
7. Create GitHub Workflow: Define CI/CD pipeline steps
8. Configure Secrets: Store credentials securely in GitHub Secrets

Quick Start

Basic Deployment Workflow

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

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-actions-ecs-role
          aws-region: us-east-1

      - name: Login to ECR
        uses: aws-actions/amazon-ecr-login@v2

      - name: Build and push image
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          ECR_REPOSITORY: my-app
          IMAGE_TAG: ${{ github.sha }}
        run: |
          docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG

      - name: Verify image push
        run: |
          docker pull $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
          echo "Image $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG verified"

      - name: Update task definition
        uses: aws-actions/amazon-ecs-render-task-definition@v1
        id: render-task
        with:
          task-definition: task-definition.json
          container-name: my-app
          image: ${{ steps.login-ecr.outputs.registry }}/my-app:${{ github.sha }}

      - name: Validate task definition
        run: |
          # Validate JSON syntax
          cat ${{ steps.render-task.outputs.task-definition }} | jq empty && echo "Task definition JSON is valid"
          # Verify container image matches expected
          CONTAINER_IMAGE=$(cat ${{ steps.render-task.outputs.task-definition }} | jq -r '.containerDefinitions[0].image')
          EXPECTED_IMAGE="${{ steps.login-ecr.outputs.registry }}/my-app:${{ github.sha }}"
          if [ "$CONTAINER_IMAGE" = "$EXPECTED_IMAGE" ]; then
            echo "Container image matches expected: $CONTAINER_IMAGE"
          else
            echo "ERROR: Container image mismatch. Expected: $EXPECTED_IMAGE, Got: $CONTAINER_IMAGE"
            exit 1
          fi

      - name: Deploy to ECS
        uses: aws-actions/amazon-ecs-deploy-task-definition@v1
        with:
          task-definition: ${{ steps.render-task.outputs.task-definition }}
          service: my-service
          cluster: my-cluster
          wait-for-service-stability: true

See references/workflow-examples.md for complete workflow examples including multi-environment and blue/green deployments.

Examples

Multi-Environment Deployment

jobs:
  deploy:
    strategy:
      matrix:
        environment: [dev, staging, prod]
    steps:
      - uses: actions/checkout@v4
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::${{ matrix.env_account }}:role/github-actions-ecs-role
          aws-region: ${{ matrix.region }}
      - name: Deploy to ${{ matrix.environment }}
        run: |
          ECR_REGISTRY=${{ env.ECR_REGISTRY }}
          docker build -t $ECR_REGISTRY/my-app:${{ github.sha }} .
          docker push $ECR_REGISTRY/my-app:${{ github.sha }}

Blue/Green Deployment with CodeDeploy

- name: Deploy with CodeDeploy
  run: |
    aws deploy create-deployment \
      --application-name my-app \
      --deployment-group-name ${{ matrix.environment }} \
      --deployment-config-name CodeDeployDefault ECSAllAtOnce \
      --revision "{\"revisionType\":\"AppSpecContent\",\"appSpecContent\":{\"content\":\"$(cat appspec.yml)\",\"filename\":\"appspec.yml\"}}"
    aws deploy wait deployment-successful --deployment-id $(aws deploy list-deployments --application-name my-app --query 'deployments[0]' --output text)

See references/workflow-examples.md for additional patterns including ECR lifecycle policies, task definition templates, and CloudFormation stack updates.

Best Practices

Security

1. Use OIDC authentication instead of long-lived IAM keys
2. Implement least privilege IAM roles with specific permissions
3. Enable ECR image scanning on push
4. Use AWS Secrets Manager for sensitive data
5. Encrypt ECR repositories with KMS
6. VPC endpoints for ECR and ECS without internet gateway
7. Security groups restrict access to minimum required

Performance

1. Docker layer caching with GitHub Actions cache
2. Multi-stage builds to minimize image size
3. Parallel deployments across multiple environments
4. Fargate Spot for cost savings on non-critical workloads
5. CloudWatch Logs with appropriate retention policies

Cost Optimization

1. ECR lifecycle policies to clean up old images
2. Fargate Spot instances for development/testing
3. Right-sized task CPU and memory
4. Auto-scaling based on metrics
5. Scheduled scaling for predictable traffic patterns

See references/best-practices.md for detailed security, performance, and cost optimization guidelines.

Common Troubleshooting

Authentication Failures

• Verify OIDC trust relationship matches GitHub organization/repository
• Check IAM role has proper permissions for ECR and ECS
• Ensure GitHub Actions repository has id-token: write permission

Deployment Failures

• Check CloudWatch Logs for application errors
• Verify task definition matches service requirements
• Ensure sufficient CPU/memory in Fargate cluster
• Review health check configuration

ECR Push Failures

• Verify repository exists and permissions are correct
• Check image tag format and registry URL
• Ensure Docker daemon is running in GitHub Actions runner
• Verify image size doesn't exceed ECR limits

CloudFormation Rollback

• Review stack events in AWS Console
• Check parameter values match resource constraints
• Verify IAM role has cloudformation:UpdateStack permission
• Enable termination protection for production stacks

See references/best-practices.md for complete troubleshooting guide with debug commands.

Related Skills

• aws-cloudformation-ecs - Design and implement ECS cluster architecture
• aws-cloudformation-lambda