---
title: GitHub Actions with AWS
description: GitHub Actions to AWS in 2026: OIDC keyless auth, Artifact Attestations, Immutable Actions, ARM runners, and reusable workflows to ECS, Lambda, EKS.
url: https://www.factualminds.com/integrations/github-actions-aws/
category: cicd
updated: 2026-04-29
---

# GitHub Actions with AWS

> Deploy to AWS automatically with GitHub Actions — OIDC-first, SLSA-aligned, and production-safe.

## 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/)

## Set up GitHub Actions to deploy to AWS using OIDC

Configure keyless authentication from GitHub Actions to AWS and run your first deploy.

1. **Create the IAM OIDC identity provider for GitHub** — In AWS IAM, create an OpenID Connect identity provider with URL https://token.actions.githubusercontent.com and audience sts.amazonaws.com. AWS manages the thumbprint rotation automatically.
2. **Create the deployment IAM role with a scoped trust policy** — Create an IAM role whose trust policy restricts the sub claim to a specific repository, branch, environment, or tag — e.g. repo:acme/web:ref:refs/heads/main or repo:acme/web:environment:production. Attach only the permissions that deployment requires (least privilege).
3. **Request id-token write permission in the workflow** — In the workflow job, set permissions: { id-token: write, contents: read }. Without id-token: write, the OIDC token is not available and the configure-aws-credentials action cannot run.
4. **Call aws-actions/configure-aws-credentials@v4 with the role ARN** — Use the action with role-to-assume set to the IAM role ARN and aws-region set to your target region. Optionally set role-session-name to include the run ID for CloudTrail traceability.
5. **Run your deployment commands** — Use AWS CLI or the official AWS actions (amazon-ecr-login, amazon-ecs-deploy-task-definition, cloudformation, etc.) in subsequent steps. The assumed-role credentials live for the job and vanish after.
6. **Emit Artifact Attestations for SLSA provenance** — Use actions/attest-build-provenance for binaries and actions/attest-build-provenance with push-to-registry: true for container images pushed to ECR. Pair with Amazon Inspector v2 and image signing on ECR to fail deploys that cannot produce verifiable provenance.

## FAQ

### How do I authenticate GitHub Actions to AWS without long-lived keys?
Use OpenID Connect (OIDC). Create an IAM OIDC identity provider for token.actions.githubusercontent.com, then an IAM role whose trust policy restricts the sub claim to specific repos, branches, environments, or tags. The aws-actions/configure-aws-credentials@v4 action exchanges the workflow's short-lived OIDC token for temporary AWS credentials — no secrets, nothing to rotate.

### How do I restrict the OIDC role so one repo cannot deploy to another project's account?
Use OIDC subject-claim filtering in the IAM role's trust policy. Require sub to equal repo:acme/payments:ref:refs/heads/main for production, or repo:acme/payments:environment:production when you use GitHub Environments. You can combine with aud checks and, for extra defense in depth, explicitly deny any session that is missing the expected tag. A single wildcard (repo:acme/*) is a common mistake that lets any repo in the org assume the role.

### What are Artifact Attestations and why do I need them for AWS deploys?
Artifact Attestations (GA 2024) produce a SLSA-v1-aligned, cryptographically signed provenance statement tying a build to the specific workflow, commit, and runner that produced it. For AWS, the pattern is: build → attest (actions/attest-build-provenance) → push to ECR with push-to-registry: true → in the deploy step verify the attestation via gh attestation verify before calling amazon-ecs-deploy-task-definition. This closes the supply-chain gap that static IAM permissions do not address.

### When should I use GitHub-hosted larger runners vs self-hosted runners on EC2?
GitHub-hosted larger runners (up to 64 vCPU, including ARM and GPU variants) are the default choice — no maintenance, isolation per job, and supply-chain guarantees from GitHub. Self-hosted runners on EC2 make sense for (a) regulated workloads that must run inside a VPC with no egress, (b) sustained high utilisation where per-minute pricing becomes uneconomic, or (c) specialised hardware AWS offers but GitHub does not (e.g., Graviton3E, Inferentia2). For self-hosted, use GitHub's Actions Runner Controller on EKS for auto-scaling rather than raw EC2 Auto Scaling groups.

### How do I handle secrets that are not AWS credentials (database URLs, third-party API keys)?
Three layers. (1) OIDC handles AWS. (2) For third-party secrets, prefer AWS Secrets Manager + Systems Manager Parameter Store fetched at runtime from Lambda/ECS, not injected into the workflow. (3) When a workflow genuinely needs a third-party secret (e.g., Stripe API key for a migration), use GitHub Environments with environment-scoped secrets and required reviewers — never repo-level secrets for production. Immutable Actions (2025) ensure the action consuming the secret cannot be silently swapped for a malicious version.

### How do reusable workflows change CI/CD governance across many repos?
Reusable workflows live in a central repo (e.g., acme/platform-workflows) and are called by every app repo via uses: acme/platform-workflows/.github/workflows/deploy.yml@v1. Your platform team owns the deployment contract (OIDC role name pattern, attestation emission, Slack notification, rollback flag) and can upgrade all callers by cutting a new tag. Combined with Immutable Actions (which pin uses: refs to an immutable SHA) and deployment protection rules, reusable workflows are the canonical 2026 way to enforce CI/CD standards at scale without CODEOWNERS gymnastics.

### What is the best rollback pattern for GitHub Actions deploys on AWS?
Three tiers. (1) For ECS/Fargate and Lambda: use CodeDeploy with canary or linear deployment and a CloudWatch alarm-based rollback — GitHub Actions kicks off the deployment, CodeDeploy handles progressive shift and automatic rollback. (2) For S3 + CloudFront static sites: keep the previous build prefix and flip the CloudFront origin or function. (3) For ad-hoc rollback: re-run the previous successful workflow run from the Actions UI, which replays the exact same SHA and attested artifact. Avoid "git revert then redeploy" as the primary rollback path — too slow under incident pressure.

---

*Source: https://www.factualminds.com/integrations/github-actions-aws/*