AWS: GitHub OIDC and IAM Roles
Set up keyless GitHub Actions authentication to AWS using OIDC, IAM roles, Atmos auth profiles, and GitHub workflows.
This guide walks you through setting up keyless authentication between GitHub Actions and AWS for Terraform CI/CD. By the end, your GitHub Actions workflows will authenticate to AWS using short-lived OIDC tokens — no static credentials required.
- 1GitHub OIDC Identity Provider — Create the trust relationship between GitHub and your AWS account.
- 2IAM Roles — Create IAM roles that GitHub Actions assumes to run Terraform, scoped to your repository.
- 3Atmos Auth Profiles — Configure the Atmos CLI to use the OIDC provider and roles at runtime.
- 4GitHub Workflows — Wire up your GitHub Actions workflows to use the auth profiles.
Everything is defined inline using Atmos source provisioning — no pre-vendored components or imports required.
Curious how all the pieces connect? Jump to How It All Fits Together.
The OIDC provider tells AWS to trust tokens issued by GitHub Actions. Deploy this once per AWS account.
components:
terraform:
github-oidc-provider:
source:
uri: github.com/cloudposse-terraform-components/aws-github-oidc-provider.git//src
version: v1.535.1
vars:
enabled: trueatmos terraform apply github-oidc-provider --stack devAfter deploying, note the provider ARN from the Terraform output — you'll need it for the IAM roles in the next step.
Create IAM roles that GitHub Actions assumes via the OIDC provider. The role's trust policy ensures only your repository can assume it.
One role with full access for both
terraform plan and terraform apply. Best for small teams or single-account setups.components:
terraform:
iam-role/terraform:
metadata:
component: iam-role
source:
uri: github.com/cloudposse-terraform-components/aws-iam-role.git//src
version: v1.537.0
vars:
enabled: true
name: terraform
role_description: |
IAM role for GitHub Actions CI/CD.
Trusts the GitHub OIDC provider for keyless authentication.
managed_policy_arns:
- arn:aws:iam::aws:policy/AdministratorAccess
# GitHub OIDC trust
github_oidc_provider_enabled: true
github_oidc_provider_arn: arn:aws:iam::111111111111:oidc-provider/token.actions.githubusercontent.com # Replace with your OIDC provider ARN
trusted_github_org: acme # Replace with your GitHub org
trusted_github_repos:
- "acme/infra-live" # Replace with your repo
policy_statements:
TerraformStateBackendAssumeRole:
effect: "Allow"
actions:
- "sts:AssumeRole"
- "sts:TagSession"
- "sts:SetSourceIdentity"
resources:
- arn:aws:iam::111111111111:role/my-tfstate-role # Replace with your TF state backend role ARNAuth profiles tell the Atmos CLI how to obtain cloud credentials at runtime. Set
ATMOS_PROFILE in your workflow to activate a profile.A single profile used for both plan and apply:
auth:
providers:
github-oidc:
kind: github/oidc
region: us-east-2 # Replace with your region
spec:
audience: sts.amazonaws.com
identities:
deploy/terraform:
default: true
kind: aws/assume-role
via:
provider: github-oidc
principal:
assume_role: arn:aws:iam::111111111111:role/acme-gbl-dev-terraform # Replace with your role ARNWire up your GitHub Actions workflows to use the auth profiles. The key requirements are:
permissions: id-token: writeso GitHub issues OIDC tokensATMOS_PROFILEenvironment variable to activate the correct auth profile
The examples below focus on the plan and apply workflows that use OIDC authentication. A complete Atmos Pro setup also requires workflows for detecting affected stacks and uploading instances. For the full set of workflows, see Configure GitHub Workflows.
With a single profile, both plan and apply workflows use the same
ATMOS_PROFILE:name: Atmos Terraform Plan
on:
workflow_dispatch:
inputs:
component:
description: "Component"
required: true
type: string
stack:
description: "Stack"
required: true
type: string
permissions:
id-token: write
contents: read
jobs:
plan:
runs-on: ubuntu-latest
container:
image: ghcr.io/cloudposse/atmos:${{ vars.ATMOS_VERSION }}
defaults:
run:
shell: bash
steps:
- uses: actions/checkout@v6
- name: Terraform Plan
env:
ATMOS_PROFILE: github
run: |
atmos terraform plan ${{ inputs.component }} -s ${{ inputs.stack }}The GitHub OIDC Identity Provider is deployed once per AWS account. It establishes a trust relationship so AWS accepts tokens issued by GitHub Actions.
IAM roles reference that OIDC provider and include a trust policy scoped to one or more specific repositories. Only workflows running in those repositories can assume the role.
Atmos auth profiles tell the Atmos CLI how to exchange a GitHub OIDC token for temporary AWS credentials by assuming a specific IAM role. You use multiple profiles so the same Atmos configuration works in different contexts — a developer profile for local usage and a CI profile for GitHub Actions.
In your GitHub Actions workflows, the
permissions block is what enables the token exchange:permissions:
id-token: write
contents: readSetting
id-token: write tells GitHub to issue a short-lived OIDC token for the workflow run. The Atmos CLI picks up that token automatically and uses the active auth profile to assume the corresponding IAM role.Finally, identities in the auth profile determine which IAM role is assumed. When an identity has
default: true, it is used automatically for all components:identities:
deploy/terraform:
default: true # Used for all components unless overridden
kind: aws/assume-role
via:
provider: github-oidc
principal:
# This is the IAM role you provisioned with the iam-role component in Step 2
assume_role: arn:aws:iam::111111111111:role/acme-gbl-dev-terraformIdentities follow the Atmos inheritance model, so you can override them at any level when specific components need different credentials.
This guide covers the OIDC and IAM foundation. To complete your Atmos Pro setup, you'll also need to:
- Import your repositories into Atmos Pro so it can monitor pull requests and dispatch workflows
- Configure repository permissions in Atmos Pro to control who can approve and apply changes
- Set up the remaining GitHub workflows — the examples above cover plan and apply, but you also need workflows for detecting affected stacks and uploading instances
Next: Configure GitHub Workflows
Set up the complete set of workflows including affected stacks detection, plan, apply, and instance uploads.