Cloud Authentication
Configure OIDC authentication between GitHub Actions and your cloud provider (AWS, Azure, GCP) using Atmos Auth Profiles. Atmos Pro never has access to your cloud.
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.
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.
For step-by-step instructions, see GitHub's guide: Configuring OpenID Connect in Amazon Web Services. For a ready-to-use CloudFormation template, see the Cloud Integrations page.
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:
my-org/deploy:
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=my-org/deployWhen an identity has
default: true set, it is used automatically if no --identity flag is provided.You can also override identities at the component level in your stack configuration. This is useful when different components need different cloud credentials — for example, a networking component that assumes a network admin role. Component auth configuration is deep-merged with global auth, and component identities override global identities with the same name.
components:
terraform:
vpc:
auth:
identities:
my-org/deploy:
kind: aws/assume-role
via:
provider: github-oidc
principal:
assume_role: arn:aws:iam::123456789012:role/network-adminFor 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.