GitHub Actions with AWS

GitHub Actions + AWS overview

GitHub Actions is GitHub’s native CI/CD platform. Workflows live in .github/workflows/ alongside the code they build. For AWS workloads, the 2026 pattern we deploy is OIDC-first (no long-lived IAM access keys in GitHub Secrets), SLSA-aligned (every artifact ships with Artifact Attestations verifiable from ECS/EKS/Lambda deploy steps), and reusable-workflow-driven (a platform team owns the deploy contract once, every app repo calls it).

What’s new in 2026

• Artifact Attestations (GA 2024) — SLSA v1 build provenance signed by Sigstore/Fulcio and tied to the workflow, commit, and runner that produced the artifact. Verify before deploying to ECR/ECS/Lambda.
• Immutable Actions (2025) — uses: refs can be pinned to an immutable SHA that GitHub guarantees cannot be silently moved. Kills tag-hijack supply-chain attacks on popular actions.
• OIDC subject-claim filtering has matured — repo:acme/*:ref:refs/heads/main patterns and environment-scoped subjects are the standard; wildcards are an audit flag.
• Larger and ARM runners — up to 64 vCPU Linux/Windows/ARM and GPU variants are GitHub-hosted, no self-hosted EC2 needed for most use cases. ARM runners are the default for building Graviton-targeted container images.
• Reusable workflows + concurrency — centralised deploy contracts with concurrency: { group: "deploy-prod", cancel-in-progress: false } prevent two production deploys from racing.
• Deployment protection rules — required reviewers, wait timers, and custom deployment-gate apps (security scan passes, SLO budget available, change freeze not active) are now first-class for GitHub Environments.
• Attestations for ECR images — push container images to ECR with push-to-registry: true in the attestation action; deploy steps verify via gh attestation verify before calling amazon-ecs-deploy-task-definition.

Why GitHub Actions for AWS deployment

Built into GitHub

• Workflows are code: reviewed in pull requests, version-controlled, same CODEOWNERS as the rest of the repo.
• Approvals and audit trail are native — no external service accounts.

Cost efficient

• Free for public repos; 2,000 minutes/month for private repos on the free plan; per-minute pricing on larger/ARM/GPU.
• ARM runners are typically 30–37% cheaper than x86 for the same build.

Official AWS support

• AWS publishes and maintains aws-actions/configure-aws-credentials@v4, amazon-ecr-login, amazon-ecs-deploy-task-definition, amazon-ecs-render-task-definition, aws-cloudformation-github-deploy, and amazon-ecr-attestations.
• Reference architectures exist for Control Tower multi-account Organisations — the IAM OIDC provider and role StackSet deploys in minutes.

Core concept: workflows

Workflows are YAML files that define:

1. Trigger — push, pull_request, schedule, workflow_dispatch, workflow_call (reusable).
2. Jobs — parallel or sequential units with their own runner and permissions.
3. Steps — commands and actions within a job.
4. Environment — runner OS/arch, permissions, secrets, and deployment protection rules.

Example flow: push to main → run tests on matrix of Node versions → build container image on an ARM runner → attest build provenance → push to ECR → verify attestation → amazon-ecs-deploy-task-definition → Slack notification on success.

Authentication: OIDC is the only defensible default

OpenID Connect (recommended)

• Short-lived credentials scoped per workflow run; no static keys anywhere.
• IAM role trust policy restricts the sub claim to specific repo, branch, environment, or tag.
• Subject-claim filtering examples we deploy:
  • repo:acme/payments:ref:refs/heads/main — production deploy from main only.
  • repo:acme/payments:environment:production — paired with a GitHub Environment that has required reviewers.
  • repo:acme/payments:pull_request — for PR-scoped preview environments with a deliberately narrower IAM role.
• Never trust a wildcard at the repo level (repo:acme/*) for a production deploy role — that lets any repo in the org assume it.

IAM access keys (legacy, do not use)

• Long-lived credentials in GitHub Secrets. High blast radius if leaked. Must rotate manually.
• Still acceptable only for personal projects or demos — never for team workloads.

Common GitHub Actions → AWS patterns

Build, attest, and push Docker to ECR

• aws-actions/amazon-ecr-login to authenticate.
• Build on ARM runner if target is Graviton (most new workloads).
• actions/attest-build-provenance with push-to-registry: true for ECR attestation.
• Deploy step verifies attestation before updating the ECS task definition.

Deploy Lambda via CloudFormation or lambda update-function-code

• Package code; for bigger dependencies use container images + amazon-ecr-login.
• Verify with a smoke-test invocation (aws lambda invoke) gated on a workflow_dispatch manual trigger for prod.

Deploy to App Runner or ECS on Fargate

• Push image; use amazon-ecs-render-task-definition to update the image digest in a committed task-def file; amazon-ecs-deploy-task-definition to roll.
• Pair with CodeDeploy for canary/linear traffic shift + auto-rollback on CloudWatch alarm.

Deploy static site to S3 + CloudFront

• Build (Astro, Next.js static, React); aws s3 sync with --delete; aws cloudfront create-invalidation.
• Use versioned prefixes (/v/${{ github.sha }}/) + CloudFront Functions for instant rollback.

Apply Terraform or AWS CDK

• terraform plan on every PR; terraform apply only on merge + environment approval.
• CDK equivalents with cdk diff → cdk deploy gated by environment approval.

Workflow structure (2026 reference)

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

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: false

jobs:
  test:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

  build-and-attest:
    needs: test
    runs-on: ubuntu-24.04-arm # Graviton-targeted images
    permissions:
      id-token: write
      contents: read
      attestations: write
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789:role/gha-ecr-push
          aws-region: us-east-1
      - uses: aws-actions/amazon-ecr-login@v2
      - run: docker buildx build --platform linux/arm64 -t $IMAGE .
      - uses: actions/attest-build-provenance@v2
        with:
          subject-name: ${{ env.ECR_REGISTRY }}/my-app
          subject-digest: ${{ steps.build.outputs.digest }}
          push-to-registry: true

  deploy:
    needs: build-and-attest
    runs-on: ubuntu-24.04
    environment: production # required reviewers + protection rules
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789:role/gha-deploy-prod
          aws-region: us-east-1
      - run: gh attestation verify oci://$IMAGE --repo $GITHUB_REPOSITORY
      - uses: aws-actions/amazon-ecs-deploy-task-definition@v2
        with:
          task-definition: task-def.json
          service: my-service
          cluster: prod
          wait-for-service-stability: true

Larger, ARM, and GPU runners

• ARM runners (ubuntu-24.04-arm) — default for building Graviton-targeted images. Typically 30–37% faster and cheaper than x86 for the same Docker build.
• Larger runners up to 64 vCPU for parallel compilation or monorepo test suites.
• GPU runners for ML model eval in CI; sufficient for integration tests against Bedrock or SageMaker endpoints.
• Self-hosted runners via Actions Runner Controller on EKS for regulated/egress-locked workloads.

GitHub Environments and deployment protection rules

• Required reviewers — named reviewers must approve before the job runs.
• Wait timers — forced delay (useful for post-deploy smoke windows before the next stage).
• Deployment branch rules — only main or tagged releases can deploy to production.
• Environment secrets — scoped to the environment; invisible to pull_request triggers.
• Custom deployment gates — external systems can block deploys (e.g., “change freeze active”, “error-budget exhausted”, “Security Hub critical findings above 0”).

Failure modes & resilience

1. GitHub-hosted runner outages. GitHub publishes incidents at githubstatus.com; Actions can stall for 5–60 minutes during regional incidents. Mitigation: critical deploys must support manual workflow_dispatch from a self-hosted runner fallback, or use AWS CodeBuild as a break-glass deploy path. Do not have only one path to production.

2. Actions minutes quota exhaustion. Free / Team plans are capped (2,000 / 3,000 minutes/month). Hitting the cap blocks all private-repo workflows org-wide. Mitigation: monitor minutes via the REST API (/orgs/{org}/settings/billing/actions); set a CloudWatch alarm via a small EventBridge-scheduled Lambda; budget alerts at 70% / 90%. ARM and larger runners are billed at higher multipliers — model before adopting.

3. ECR pull rate limits during deploy. ECR is generous but VPC endpoints with low concurrency can throttle. For high-velocity deploys (>50 task definitions/min), pre-cache base layers with image-pull-policy: IfNotPresent and run an ECR pull-through cache for non-AWS public images.

4. CodeDeploy alarm-rollback edge cases. The CloudWatch alarm used for auto-rollback evaluates at the alarm’s period; a low-volume canary may not trip a > X errors per 5 min alarm before traffic shifts to 100%. Pair with a synthetic Canary (CloudWatch Synthetics) running every minute against the canary task group, and use that as the rollback alarm.

5. OIDC token-exchange throttling. STS AssumeRoleWithWebIdentity is rate-limited per role (5,000 transactions/sec account-wide, lower per role). Massive matrix builds assuming the same role can throttle. Mitigation: split into per-environment roles, or stagger jobs with concurrency groups.

6. Reusable workflow upgrades break callers. Pinning callers to @v1 (mutable major) means a compatibility break in a v1.x.x release blasts all repos. Use SemVer with immutable SHA refs for production; cut a @v2 for breaking changes and migrate callers explicitly.

7. Action supply-chain compromise. A malicious tag-push on a popular community action would historically run with workflow secrets. Mitigation: Immutable Actions (2025) — pin uses: to a SHA that GitHub guarantees immutable; also enable the org-level “allow specified actions” allow-list.

Observability runbook

Metrics worth surfacing:

Debug path: “deploy job failed”:

1. Workflow run page → failed step → expand log; copy the exact AWS API error.
2. CloudTrail in the target account → filter by the OIDC role’s session name (set role-session-name to include ${{ github.run_id }}) → identify the denying API call.
3. If AccessDenied: validate the IAM trust policy sub claim allows this branch/environment, and the role’s permission policy includes the failing API.
4. If Throttling: reduce job concurrency, add aws-actions/configure-aws-credentials retry with role-duration-seconds, or move heavy work to AWS-side (CodeBuild) to eliminate the runner→AWS chatty path.
5. Attestation failures: gh attestation verify oci://<image> --repo <repo> locally; check that the actions/attest-build-provenance action ran in the build job, and the deploy job has attestations: read permission.

Incident attachment: for any production deploy incident, attach gh run view <run-id> --log output to the postmortem alongside CloudTrail event IDs from the target account. Log retention on free/Team plans is 90 days; archive critical incident logs to S3 if your compliance regime requires longer.

When GitHub Actions is NOT the right call

• You need tight integration with an existing Jenkins/GitLab CI/CodeBuild estate and cannot justify migration — a hybrid where GitHub Actions only runs code-level CI and a separate orchestrator handles deploys can be defensible but doubles the review surface.
• You need long-running jobs (>6 hours) that cannot be broken into stages — consider AWS CodeBuild with elastic compute or a self-hosted runner on EC2.
• Your workloads are so regulated that no runner can have egress — self-hosted runners inside the VPC work, but at that point AWS CodePipeline + CodeBuild often has lower audit overhead.

Best practices

Security

• OIDC only; no static keys.
• Subject-claim filtering scoped to repo + branch or repo + environment; no wildcards.
• Immutable Actions — pin uses: refs to a SHA that GitHub guarantees immutable.
• Artifact Attestations on every artifact; verify before deploy.
• GitHub Environments with required reviewers + deployment protection rules for production.

Efficiency

• Cache node_modules, pip, Docker layers, and Turborepo/Nx outputs.
• Matrix builds for multi-runtime testing; ARM runners for Graviton images.
• Split test and deploy jobs so failing tests abort before any AWS calls.

Reliability

• terraform plan or cdk diff as a required PR check before apply.
• CodeDeploy canary/linear for ECS and Lambda with CloudWatch alarm rollback.
• Concurrency groups prevent two prod deploys from racing.
• Re-run previous successful workflow for fastest rollback; avoid “revert + redeploy” as primary rollback.

Related reading

• GitHub Actions + AWS: CI/CD security best practices
• DevOps on AWS: CodePipeline vs GitHub Actions vs Jenkins
• Cost-aware CI/CD pipelines on AWS

Related services

• DevOps Pipeline Setup
• AWS Application Modernization
• Hire a Dedicated AWS Expert