Cloud Authentication
Configure OIDC authentication between GitHub Actions and your cloud provider (AWS, Azure, GCP) using Atmos Auth Profiles, and set up your Terraform state backend. Atmos Pro never has access to your cloud.
Atmos Pro doesn't run Terraform or Atmos itself — it dispatches GitHub Actions that you control. To run Terraform in those GitHub Actions, you need two things in your cloud environment:
- 1Terraform State Backend to store Terraform state. If you already have one, you can skip to configuring OIDC.
- 2OIDC Integration with GitHub so your workflows can authenticate with your cloud provider using short-lived credentials. Static credentials are strongly discouraged.
Terraform requires a state backend to store its state files. If you already have one configured, skip ahead to OIDC Authentication.
Atmos can manage your state backend for you — both configuring where state is stored and automatically provisioning the underlying infrastructure (e.g., S3 bucket). This is optional but recommended, especially for new projects.
S3 Native Locking
Terraform 1.10+ and OpenTofu 1.8+ support native S3 state
locking via
use_lockfile: true. All
examples on this page use S3 native locking.Tell Atmos where to store Terraform state by configuring the backend in your stack defaults. This is required if you want Atmos to manage your backend — including automatic provisioning.
terraform:
backend_type: s3
backend:
s3:
bucket: my-backend-tfstate
use_lockfile: true
role_arn: null # Set to null to use the current AWS credentials
encrypt: true
key: terraform.tfstate
acl: bucket-owner-full-control
region: us-east-1 # Ensure this matches the region where the backend was deployed
remote_state_backend:
s3:
role_arn: null # Set to null to use the current AWS credentialsWith the backend configured above, you can optionally enable automatic provisioning. Atmos will create the S3 bucket with secure defaults — versioning, encryption, public access blocked, and native S3 locking — on your first
atmos terraform init.settings:
provision:
backend:
enabled: trueYou can also provision backends explicitly:
atmos terraform backend create vpc --stack devFor complete documentation, see Automatic Backend Provisioning on the Atmos docs.
When your GitHub Actions workflows run Terraform, they need credentials to access your cloud provider (AWS, Azure, or GCP). Setting this up requires two things:
- 1Configure a trust relationship between GitHub's OIDC provider and your cloud account, so your cloud provider accepts tokens from GitHub Actions.
- 2Configure an Atmos Auth Profile that tells the Atmos CLI how to use that trust relationship to obtain short-lived cloud credentials at runtime.
Atmos Pro is not involved in this flow. Cloud authentication happens entirely between GitHub Actions, the Atmos CLI, and your cloud provider. Atmos Pro never sees or handles your cloud credentials—it only orchestrates when workflows run. For Atmos Pro API authentication (a separate flow), see the Authentication page.
An Auth Profile is a named configuration directory (e.g.,
profiles/github/atmos.yaml) that tells the Atmos CLI how to obtain cloud credentials in a given context. Profiles let you define one set of OIDC providers and identities, then activate the same profile in both CI and local development — ensuring consistent, reproducible authentication everywhere. In GitHub Actions, set ATMOS_PROFILE: github to load the profile; locally, pass --profile github to any Atmos command.Identity Naming Convention
Name identities after permission boundaries, not deployment contexts — e.g.,
acme/admin and acme/planner
rather than deploy/terraform or github/role. The profile already captures the context (GitHub OIDC vs. local SSO);
the identity name should describe the level of access. This keeps names stable across profiles and makes stack
configuration self-documenting. For a detailed guide, see Naming Identities.Select your cloud provider below for both the trust relationship setup and the corresponding Auth Profile configuration.
Before your Auth Profile will work, you must configure AWS to trust GitHub OIDC tokens:
- 1Create the GitHub OIDC Identity Provider in AWS. Add
token.actions.githubusercontent.comas an OpenID Connect provider in your AWS account. - 2Create an IAM role that trusts the GitHub OIDC provider. The role's trust policy must allow
sts:AssumeRoleWithWebIdentityfromtoken.actions.githubusercontent.comand scope it to your repository. - 3Attach the necessary permissions to the IAM role for your Terraform/OpenTofu operations.
The IAM role's trust policy uses the OIDC
sub (subject) claim to control which workflow contexts can assume the role. By default, scoping to just a repository name (e.g., repo:acme/infra-live:*) allows any branch, pull request, or GitHub Environment in that repository to assume the role. To restrict access — for example, allowing only a production GitHub Environment to assume a privileged role — append a constraint to the subject claim (e.g., repo:acme/infra-live:environment:production). This is essential for separating read-only plan roles from full-access apply roles.For a complete walkthrough including OIDC provider setup, IAM roles, environment scoping, and Atmos integration, see AWS: GitHub OIDC and IAM Roles. For general OIDC background, see GitHub's guide: Configuring OpenID Connect in Amazon Web Services.
Use the
aws/assume-role identity kind to assume an IAM role using a GitHub OIDC token.auth:
providers:
github-oidc:
kind: github/oidc
region: us-east-2
spec:
audience: sts.amazonaws.com
identities:
acme/admin:
default: true
kind: aws/assume-role
via:
provider: github-oidc
principal:
assume_role: arn:aws:iam::123456789012:role/github-actions-roleIn your GitHub Actions workflow, set the
ATMOS_PROFILE environment variable to load the profile:env:
ATMOS_PROFILE: githubOr pass it directly to the CLI:
atmos terraform plan mystack --profile githubWhen multiple identities are defined in a profile, select which one to use with the
--identity flag:atmos terraform plan mystack --identity=acme/adminWhen an identity has
default: true set, it is used automatically if no --identity flag is provided.When different components need different cloud credentials, define all identities in your Auth Profile and then select which identity a component should use in the stack configuration. Component auth configuration is deep-merged with the profile, so you only need to set
default: true on the desired identity — the full definition stays in the profile.First, define multiple identities in the profile:
auth:
providers:
github-oidc:
kind: github/oidc
region: us-east-2
spec:
audience: sts.amazonaws.com
identities:
acme/admin:
default: true
kind: aws/assume-role
via:
provider: github-oidc
principal:
assume_role: arn:aws:iam::123456789012:role/github-actions-role
acme/network:
kind: aws/assume-role
via:
provider: github-oidc
principal:
assume_role: arn:aws:iam::123456789012:role/network-adminThen, in the stack configuration, select which identity a component should use:
components:
terraform:
vpc:
auth:
identities:
acme/network:
default: trueThis overrides the default identity for the
vpc component without redefining the identity itself — the full configuration is inherited from the profile.For more details, see the Atmos Identities documentation.
For complete documentation on Auth Profiles, including advanced configuration options, see the Atmos Auth Profiles documentation.
Next: Configure GitHub Workflows
Now that cloud authentication is configured, set up your GitHub Actions workflows to work with Atmos Pro.