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)

```yaml
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:**

| Signal                                         | Source                              | Alarm threshold / action                                          |
| ---------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------- |
| Workflow `success_rate` per repo               | REST `/repos/{}/actions/runs`       | `< 95%` over 24h → review failing job logs                        |
| Actions minutes consumed                       | `/orgs/{}/settings/billing/actions` | `> 70%` of monthly quota at day 20 → review heavy-use repos       |
| OIDC `AssumeRoleWithWebIdentity` count by role | CloudTrail                          | Sudden spike on a single role → check matrix size, concurrency    |
| Deploy duration p95                            | Workflow run timing                 | `> baseline + 50%` → investigate runner health, dependency caches |
| Attestation verify failure                     | `gh attestation verify` exit        | Any failure on production deploy → block; investigate provenance  |

**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`](/blog/github-actions-aws-cicd-security-best-practices/)
- [`DevOps on AWS: CodePipeline vs GitHub Actions vs Jenkins`](/blog/devops-on-aws-codepipeline-vs-github-actions-vs-jenkins/)
- [`Cost-aware CI/CD pipelines on AWS`](/blog/cost-aware-cicd-pipelines-aws/)

## Related services

- [DevOps Pipeline Setup](/services/devops-pipeline-setup/)
- [AWS Application Modernization](/services/aws-application-modernization/)
- [Hire a Dedicated AWS Expert](/services/hire-a-dedicated-aws-expert/)

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