GitHub Actions for AWS: Secure CI/CD Pipeline Patterns That Ship Code Safely

In March 2023, the tj-actions/changed-files GitHub Action was compromised. Attackers pushed malicious code that printed CI secrets — including AWS credentials, npm tokens, and GitHub tokens — to public workflow logs. Over 23,000 repositories had used this action. Every one of them was potentially exposed.

The pipeline that was supposed to automate safe deployments had become the attack surface.

This is not an edge case. Supply chain attacks targeting CI/CD systems have increased every year since 2020. The combination of broad repository access, stored cloud credentials, and automated execution makes a poorly configured GitHub Actions pipeline one of the most dangerous assets in your infrastructure.

This guide covers the six non-negotiable security principles and the production deployment patterns — OIDC federation, pinned actions, least-privilege permissions, blue-green deployments, build caching, and environment promotion — that ship code safely on AWS.

The Six Non-Negotiables

Before any implementation detail, these six principles apply to every pipeline, every workflow, every job:

These are not aspirational guidelines. They are the baseline. Every pattern in this guide is built on top of them.

OIDC Federation: Eliminate AWS Access Keys From CI/CD

The single most impactful security change you can make to your GitHub Actions pipelines is eliminating stored AWS credentials.

The old approach — storing AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as GitHub secrets — has a fundamental problem: these are long-lived credentials. If your workflow is compromised, the attacker has keys that remain valid until someone notices and rotates them. In many incidents, that window is days or weeks.

OIDC federation eliminates this entirely. GitHub Actions can request a short-lived JWT from GitHub’s OIDC provider, and AWS will exchange that token for temporary credentials scoped to a specific IAM role. No stored secrets. No rotation required. Credentials expire automatically after the job completes.

Setting Up OIDC

Step 1: Create the IAM OIDC Identity Provider in AWS

aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com \
  --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1

This is a one-time setup per AWS account.

Step 2: Create the IAM Role with a Trust Policy

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

The sub condition locks this role to your specific repository. An attacker who compromises a different repository cannot assume this role.

For tighter control, restrict to a specific branch or environment:

"token.actions.githubusercontent.com:sub": "repo:your-org/your-repo:ref:refs/heads/main"

Step 3: Use the Role in Your Workflow

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write    # Required for OIDC
      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-deploy
          aws-region: us-east-1

No AWS_ACCESS_KEY_ID. No AWS_SECRET_ACCESS_KEY. The configure-aws-credentials action handles the OIDC token exchange automatically.

Result: Temporary credentials valid for the job duration, automatically expired, scoped to exactly the IAM role you defined. If the workflow is compromised, the attacker gets credentials that expire in minutes and are limited to what that specific deployment role allows.

Pinning Actions Against Supply Chain Attacks

The tj-actions incident demonstrated what happens when a widely-used action is compromised at a mutable tag. The attack vector is simple: an attacker gains write access to an action repository and pushes malicious code to a tag like @v1 or @main. Every workflow using that tag gets the malicious version on its next run.

Understanding the Risk Levels

Recommendation:

• For official GitHub Actions (actions/*) and AWS official actions (aws-actions/*): @v4 or @v4.x.x is acceptable — these organizations have strong security practices and release processes
• For third-party community actions: SHA digest only
• For any action with access to credentials or secrets: SHA digest always

# Acceptable — official, well-maintained actions at version tag
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- uses: aws-actions/configure-aws-credentials@v4

# Required for third-party actions — SHA pin
- uses: some-community/action@a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

To find the SHA for any action version, check the action’s release page or run:

gh api repos/actions/checkout/git/refs/tags/v4 --jq '.object.sha'

Add a comment with the version for human readability:

# actions/checkout@v4.1.1
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683

Tools like Dependabot and Renovate can automate SHA pin updates when new versions are released.

Least-Privilege Permission Scoping

By default, GITHUB_TOKEN is granted permissions based on your repository settings — often read-all or even write-all for legacy configurations. A compromised workflow with write permissions can push to your repository, create releases, modify secrets, and trigger other workflows.

Always declare explicit permissions at the job level:

jobs:
  # Read-only PR check — no write access needed
  test:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

  # Deploy job needs specific write permissions
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write    # OIDC token for AWS
      contents: read     # Checkout code
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: ./scripts/deploy.sh

Common permission patterns:

Set the repository-level default to the most restrictive option:

# At the top of every workflow file
permissions:
  contents: read    # Repository-wide default

jobs:
  # Individual jobs override only what they need
  deploy:
    permissions:
      id-token: write
      contents: read

Never use permissions: write-all. If a step fails with a permission error, add only the specific permission it needs — do not escalate to write-all as a shortcut.

Blue-Green Deployments via GitHub Actions + CodeDeploy

Blue-green deployment is the production deployment pattern that eliminates downtime and enables instant rollback. GitHub Actions handles building and pushing your container image; AWS CodeDeploy handles the traffic shifting and automatic rollback.

Architecture:

GitHub Push (main)
  → GitHub Actions: build, test, push image to ECR
    → Update ECS task definition with new image SHA
      → CodeDeploy: Create green task set
        → Health checks pass
          → Traffic shift: 10% → green (canary validation)
            → [5 minutes observation]
              → 100% traffic → green
                → Blue task set retained for 1-hour rollback window

Complete Workflow

name: Deploy to Production

on:
  push:
    branches: [main]

permissions:
  contents: read
  id-token: write

env:
  AWS_REGION: us-east-1
  ECR_REPOSITORY: my-app
  ECS_SERVICE: my-app-service
  ECS_CLUSTER: production
  CONTAINER_NAME: my-app

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    outputs:
      image: ${{ steps.build-image.outputs.image }}

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
          aws-region: ${{ env.AWS_REGION }}

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

      - name: Build, tag, and push image
        id: build-image
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          IMAGE_TAG: ${{ github.sha }}
        run: |
          docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
          echo "image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_OUTPUT

  deploy:
    needs: build-and-push
    runs-on: ubuntu-latest
    environment: production

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Download task definition
        run: |
          aws ecs describe-task-definition \
            --task-definition my-app \
            --query taskDefinition \
            > task-definition.json

      - name: Update task definition with new image
        id: task-def
        uses: aws-actions/amazon-ecs-render-task-definition@v1
        with:
          task-definition: task-definition.json
          container-name: ${{ env.CONTAINER_NAME }}
          image: ${{ needs.build-and-push.outputs.image }}

      - name: Deploy to ECS via CodeDeploy
        uses: aws-actions/amazon-ecs-deploy-task-definition@v2
        with:
          task-definition: ${{ steps.task-def.outputs.task-definition }}
          service: ${{ env.ECS_SERVICE }}
          cluster: ${{ env.ECS_CLUSTER }}
          wait-for-service-stability: true
          codedeploy-appspec: appspec.json
          codedeploy-application: my-app-codedeploy
          codedeploy-deployment-group: production-deployment-group

appspec.json — CodeDeploy traffic shifting config:

{
  "version": 0.0,
  "Resources": [
    {
      "TargetService": {
        "Type": "AWS::ECS::Service",
        "Properties": {
          "TaskDefinition": "<TASK_DEFINITION>",
          "LoadBalancerInfo": {
            "ContainerName": "my-app",
            "ContainerPort": 3000
          }
        }
      }
    }
  ],
  "Hooks": [
    {
      "BeforeAllowTraffic": "arn:aws:lambda:us-east-1:123456789012:function:PreDeployCheck"
    },
    {
      "AfterAllowTraffic": "arn:aws:lambda:us-east-1:123456789012:function:PostDeployValidation"
    }
  ]
}

Tag your ECR images with the git commit SHA — ${{ github.sha }}. This creates a direct, traceable link from every running container back to the exact source code commit that produced it. When a production incident occurs at 2 AM, you need to know exactly what code is running.

Rollback: If CloudWatch alarms trigger during the canary window, CodeDeploy automatically shifts traffic back to the blue task set. Blue remains available for one hour after deployment — the rollback window. If a problem surfaces after the full traffic shift, you can manually trigger a rollback to the previous task set within that window.

Canary Deployments with Automated Rollback

Canary deployments take a more gradual approach than blue-green: a small percentage of traffic is routed to the new version, then incrementally increased while automated monitoring validates the release.

Traffic progression:

5% → new version, 95% → current    (10-minute observation)
25% → new version, 75% → current   (10-minute observation)
50% → new version, 50% → current   (10-minute observation)
100% → new version                 (complete)

At each step, automated checks query your monitoring system. If error rate or latency exceeds acceptable thresholds, the deployment halts and rolls back to 0%.

CodeDeploy deployment configuration for ECS:

CodeDeployDefault.ECSCanary10Percent5Minutes
  → 10% traffic to new version, wait 5 minutes, then 100%

CodeDeployDefault.ECSLinear10PercentEvery3Minutes
  → +10% every 3 minutes until 100%

Custom (recommended for production):
  → 5% for 10 minutes, then 25% for 10 minutes, then 100%

Connecting CloudWatch alarms to automatic rollback:

# In your CodeDeploy deployment group configuration
DeploymentGroupConfiguration:
  AlarmConfiguration:
    Alarms:
      - Name: HighErrorRate
      - Name: HighP99Latency
    Enabled: true
    IgnorePollAlarmFailure: false
  AutoRollbackConfiguration:
    Enabled: true
    Events:
      - DEPLOYMENT_FAILURE
      - DEPLOYMENT_STOP_ON_ALARM

Alarm thresholds:

HighErrorRate:
  Metric: HTTPCode_Target_5XX_Count
  Threshold: 10 errors per minute
  EvaluationPeriods: 2
  ComparisonOperator: GreaterThanThreshold

HighP99Latency:
  Metric: TargetResponseTime
  Statistic: p99
  Threshold: 2 seconds
  EvaluationPeriods: 2
  ComparisonOperator: GreaterThanThreshold

The error rate threshold is deliberately conservative. A new deployment that introduces a 0.01% error rate increase on high-traffic services represents thousands of failed requests per hour. Catch it at 5% traffic before it affects all users.

Build Caching: Cut Build Times 50–80%

Build caching is the highest-leverage optimization for CI cost and developer experience. Dependency installation — npm install, pip install, gradle dependencies — typically accounts for 40–70% of total build time. With caching, dependencies are restored from a cache hit in seconds rather than downloaded fresh every run.

Dependency Caching with actions/cache

- name: Cache node modules
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

- name: Install dependencies
  run: npm ci

The cache key includes a hash of package-lock.json. When dependencies change, the lock file changes, the hash changes, and a fresh cache is created. When nothing changes, the same cache is restored — skipping npm ci entirely or reducing it to a few seconds of validation.

Cache strategies by ecosystem:

# Node.js
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

# Python
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}

# Java (Gradle)
path: |
  ~/.gradle/caches
  ~/.gradle/wrapper
key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}

# Java (Maven)
path: ~/.m2
key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}

# Go
path: ~/go/pkg/mod
key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}

Docker Layer Caching

Docker builds are expensive when every layer is rebuilt from scratch. Cache layers using the GitHub Actions cache backend:

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3

- name: Build and push
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: ${{ env.ECR_REGISTRY }}/${{ env.ECR_REPOSITORY }}:${{ github.sha }}
    cache-from: type=gha
    cache-to: type=gha,mode=max

mode=max caches all intermediate layers, not just the final image. For Dockerfiles with many dependency installation steps (e.g., RUN npm ci before COPY src/), this can reduce Docker build time from 4 minutes to 30 seconds on cache hit.

Structure your Dockerfile for maximum cache effectiveness:

# These layers change rarely — cache them aggressively
FROM node:20-alpine AS base
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --only=production

# This layer changes on every commit — rebuild only this
FROM base AS production
COPY src/ ./src/
RUN npm run build

Monorepo: Build Only What Changed

For monorepos, rebuilding every package on every commit is wasteful. Use affected-build detection:

- name: Detect changed packages
  id: affected
  run: |
    # Using NX
    npx nx show projects --affected --base=origin/main > affected.txt
    echo "packages=$(cat affected.txt | tr '\n' ',')" >> $GITHUB_OUTPUT

- name: Build affected packages only
  run: npx nx run-many --target=build --projects=${{ steps.affected.outputs.packages }}

In a 20-service monorepo, changing one service rebuilds one service — not all twenty. CI cost and time scale with the change, not with the repository size.

Cost impact of caching:

At GitHub Actions pricing ($0.008/minute on Linux runners), a team running 50 builds per day saves roughly $1,000/month on build costs with effective caching.

Environment Promotion Workflow

Production deployments should follow a structured promotion path: build once, promote through environments, deploy to production only after human approval.

Why build once? If you build separate Docker images for staging and production, you are not testing what you deploy. A build-once model ensures the exact artifact validated in staging is what runs in production.

Build (on push to main)
  → Push image to ECR (tagged: commit SHA)
    → Auto-deploy to staging
      → Run integration + smoke tests against staging
        → Manual approval gate (required reviewer)
          → Deploy same image to production

GitHub Environments with Required Reviewers

name: Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      image-tag: ${{ github.sha }}
    steps:
      - uses: actions/checkout@v4
      - name: Build and push
        # ... build steps ...

  deploy-staging:
    needs: build
    runs-on: ubuntu-latest
    environment: staging    # Maps to GitHub Environment
    steps:
      - name: Deploy to staging
        run: |
          aws ecs update-service \
            --cluster staging \
            --service my-app \
            --task-definition my-app:${{ needs.build.outputs.image-tag }}

  integration-tests:
    needs: deploy-staging
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run integration tests
        run: npm run test:integration
        env:
          API_URL: https://staging.myapp.com

  deploy-production:
    needs: [build, integration-tests]
    runs-on: ubuntu-latest
    environment: production    # Required reviewers block here
    steps:
      - name: Deploy to production
        run: |
          aws ecs update-service \
            --cluster production \
            --service my-app \
            --task-definition my-app:${{ needs.build.outputs.image-tag }}

Configure the production GitHub Environment with:

• Required reviewers — one or two senior engineers who approve production deployments
• Wait timer — optional delay after approval before deployment executes
• Deployment branch rule — restrict production deployments to the main branch only

When the deploy-production job is reached, the workflow pauses. Approvers receive a notification, review the change (the PR linked to the commit, integration test results), and approve or reject. Only after approval does the deployment proceed — using the same image SHA that passed staging.

Reusable Workflows

When the same build and deploy steps appear across multiple repositories, extract them into reusable workflows. DRY pipelines mean a security fix or optimization in the shared workflow propagates to all callers automatically.

Reusable workflow (.github/workflows/deploy-ecs.yml in a central repo):

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
      service-name:
        required: true
        type: string
      cluster:
        required: true
        type: string
    secrets:
      AWS_DEPLOY_ROLE_ARN:
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
          aws-region: us-east-1

      - name: Deploy to ECS
        run: |
          aws ecs update-service \
            --cluster ${{ inputs.cluster }} \
            --service ${{ inputs.service-name }} \
            --force-new-deployment

Caller workflow (in each application repo):

jobs:
  deploy:
    uses: your-org/.github/.github/workflows/deploy-ecs.yml@main
    with:
      environment: production
      service-name: my-app
      cluster: production
    secrets:
      AWS_DEPLOY_ROLE_ARN: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}

When to extract into a reusable workflow:

• The same build steps appear in 3 or more repositories
• Security-sensitive steps (credential setup, vulnerability scanning) should be standardized
• You want enforcement — callers cannot skip steps defined in the reusable workflow

Organization-level reusable workflows live in the .github repository and can be called by any repository in your organization.

Rollback Strategy

Rollback must be faster than the original deployment. If restoring from failure takes longer than the deployment itself, your rollback is a second deployment event — with all the same risks.

Rollback methods, fastest to slowest:

Blue-green instant rollback (within the 1-hour window after deployment):

aws deploy stop-deployment \
  --deployment-id d-ABC123 \
  --auto-rollback-enabled

CodeDeploy shifts traffic back to the blue task set. Running containers are not terminated — traffic routing simply returns to the previous version. Users experience no downtime.

ECS rollback to previous task definition:

# Find the previous task definition revision
PREVIOUS=$(aws ecs describe-task-definition \
  --task-definition my-app \
  --query 'taskDefinition.revision' \
  --output text)

ROLLBACK=$((PREVIOUS - 1))

# Update service to previous revision
aws ecs update-service \
  --cluster production \
  --service my-app \
  --task-definition my-app:$ROLLBACK

Database migrations and rollback: The most common reason rollbacks fail is a database migration that is not backward-compatible. Always write migrations that run in two phases:

1. Phase 1 (deploy with new code): Add the new column as nullable. Both old and new code work.
2. Phase 2 (after rollback window closes): Make the column required, drop the old column.

Never drop a column in the same deployment that removes the code that reads it. If you roll back the code, the column is gone and the old code crashes.

Every deployment PR should include a rollback runbook:

## Rollback Plan

If this deployment causes issues:

1. Immediate (< 1 hour post-deploy):
   `aws deploy stop-deployment --deployment-id $DEPLOYMENT_ID --auto-rollback-enabled`

2. After rollback window:
   `aws ecs update-service --cluster production --service my-app --task-definition my-app:$PREVIOUS_REVISION`

3. Database: No schema changes in this deployment. Rollback is safe.

Previous task definition: my-app:42
Previous image: 123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:abc123def

Monitoring Pipeline Health

A deployment is not complete when the pipeline finishes. It is complete when production metrics confirm the new version is performing correctly.

Tag every deployment with traceable metadata:

- name: Tag deployment
  run: |
    echo "Deployment metadata:"
    echo "  Commit: ${{ github.sha }}"
    echo "  Author: ${{ github.actor }}"
    echo "  Workflow: ${{ github.workflow }}"
    echo "  Run: ${{ github.run_id }}"
    echo "  Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

This output is preserved in the GitHub Actions run log. When a production incident occurs, you can identify the exact deployment run, the commit, and the author in seconds.

CloudWatch alarms to monitor after deployment:

SNS notifications for pipeline events:

- name: Notify on failure
  if: failure()
  run: |
    aws sns publish \
      --topic-arn ${{ secrets.ALERTS_SNS_TOPIC }} \
      --message "DEPLOYMENT FAILED: ${{ github.repository }} commit ${{ github.sha }} by ${{ github.actor }}"
      --subject "Deployment Failure"

Add status badges to your README:

![Deploy](https://github.com/your-org/your-repo/actions/workflows/deploy.yml/badge.svg)

A red badge is immediately visible to every engineer who opens the repository. It creates social pressure to fix broken builds quickly.

Common Anti-Patterns

Building Pipelines That Last

A well-designed GitHub Actions pipeline is not just a deployment mechanism — it is a safety system. It enforces code review through required checks. It validates every change through automated tests. It controls access to production through environment protection rules. It creates an immutable audit trail of every deployment.

The patterns in this guide — OIDC federation, SHA-pinned actions, least-privilege permissions, blue-green deployments, build caching, and structured environment promotion — are the difference between a pipeline that ships code and a pipeline that ships code safely.

If you’re building this on AWS, the natural complement to GitHub Actions is AWS CodeDeploy for deployment orchestration and IAM with least-privilege access for every pipeline role. Secrets Manager and Parameter Store handle runtime secrets. CloudWatch monitors deployment health. These services fit together into a deployment platform that is auditable, recoverable, and resilient by design.

For hands-on help designing and implementing secure CI/CD pipelines on AWS — including GitHub Actions workflows, CodeDeploy blue-green configurations, and cross-account pipeline architecture — see our DevOps Pipeline Setup services.

Contact us to secure your deployment pipeline →