Atmos Auth and Identities for CI

[brucex]

after setting up atmos auth....when running in github CI....how does the stack know which identity to use when it needs to assume a role per account?
I can set ATMOS_PROFILE=ci and it'll assume the default identity, but what happens when after determine affected stacks...and it automatically kicks off TF plan...how does it know which identity to use?

do i need to setup .atmos/profiles in each stack folder?

Profile CI

auth:
  providers:
    github-oidc:
      kind: github/oidc
      region: us-east-1

  identities:
    identity-gitops:
      kind: aws/assume-role
      default: true
      via:
        provider: github-oidc
      principal:
        assume_role: arn:aws:iam::123456789:role/identity-gitops


    plat-prod-tfplan:
      kind: aws/assume-role
      via:
        identity: identity-gitops
      principal:
        assume_role: arn:aws:iam::123454444444444:role/acme-plat-gbl-prod-planner
    plat-prod-tfapply:
      kind: aws/assume-role
      via:
        identity: identity-gitops
      principal:
        assume_role: arn:aws:iam::123454444444444:role/acme-plat-gbl-prod-terraform

    plat-staging-tfplan:
      kind: aws/assume-role
      via:
        identity: identity-gitops
      principal:
        assume_role: arn:aws:iam::123456777777:role/acme-plat-gbl-staging-planner
    plat-staging-tfapply:
      kind: aws/assume-role
      via:
        identity: identity-gitops
      principal:
        assume_role: arn:aws:iam::123456777777:role/acme-plat-gbl-staging-terraform

[milldr]

Great question! Here's how the identity resolution works:

1 - Stack Identity Configuration

Each stack defines which identity to use in its defaults under auth.identities. For example, in stacks/orgs/acme/plat/dev/_defaults.yaml:

# Default identity for this account
# Profile determines what plat-dev/terraform resolves to (Permission Set vs IAM role)
auth:
  identities:
    plat-dev/terraform:
      default: true

This tells Atmos: "When running Terraform for any component in this stack, use the plat-dev/terraform identity."

2 - Profiles Define How to Assume Identities

Profiles are defined in the profiles/ directory, with each profile in its own folder containing an atmos.yaml:

profiles/
├── github-plan/
│   └── atmos.yaml
├── github-apply/
│   └── atmos.yaml
├── devops/
│   └── atmos.yaml
└── developers/
    └── atmos.yaml

Set the active profile via ATMOS_PROFILE environment variable. Atmos then looks up identity names (like plat-dev/terraform) in that profile's atmos.yaml to determine which IAM role or Permission Set to assume.

3 - The Naming Convention Matters

In the latest version of the reference architecture, identities follow the pattern:
<tenant>-<stage>/terraform — e.g., plat-prod/terraform, plat-staging/terraform

Your current profile has identities named differently:
plat-prod-tfplan, plat-prod-tfapply, etc.

For this to work, either:

1. Rename your identities to match what the stacks expect (plat-prod/terraform)
2. Or update your stack defaults to reference your naming convention

4 - Plan vs Apply Profiles

Typically you'd have two profiles:

1. github-plan — maps plat-prod/terraform → the planner role
2. github-apply — maps plat-prod/terraform → the terraform (apply) role

The GitHub workflows set ATMOS_PROFILE=github-plan for PR checks and ATMOS_PROFILE=github-apply for merges to main. Same identity names, different role mappings.

Docs

1. Identity Layer Overview
2. Atmos Auth Configuration
3. Deploying Identity Roles