Skip to main content

Atmos Pro

Atmos CLI handles the execution layer — how you architect your cloud infrastructure, run automation reproducibly across local and CI, and manage authentication. Atmos Pro is the control plane above that, giving you visibility and coordination across all your teams, repositories, and environments.

Atmos Pro

Why Atmos Pro?​

Atmos CLI solves the problems every company encounters: structuring Terraform at scale, running the same automation locally and in CI, handling auth, installing toolchains, managing component dependencies, keeping configuration DRY with inheritance and templating, and vendoring components across repositories. It owns the execution layer — plan, apply, deploy.

Atmos Pro solves what happens when you scale that up. Multiple repositories, multiple GitHub organizations, dozens of teams, hundreds of components. You need to know what changed, what's drifting, what's failing, who approved what, and what the current state of every deployment is — across everything.

Because Atmos CLI already handles execution, Atmos Pro doesn't need elevated access to your cloud accounts. It receives what the CLI uploads — affected stacks, component inventories, plan results — and gives you the coordination layer on top:

  • Visibility — See what's affected on every PR, across every repo and organization
  • Drift detection — Know which stacks have drifted and trigger remediation automatically
  • Approvals and change requests — Coordinate who can apply what, with full audit trails
  • Failing runs — Stay on top of failures across all teams without digging through CI logs
  • Stack locking — Prevent concurrent modifications during deployments
  • Inventory — Understand what's deployed, where, and with what configuration

Quick Start​

1. Configure Your Workspace​

atmos.yaml

settings:
  pro:
    workspace_id: "your-workspace-id"

2. Add Workflow Permissions​

.github/workflows/atmos.yaml

permissions:
  id-token: write   # Required for OIDC token exchange with Atmos Pro
  contents: read

3. Upload Affected Stacks from Your Workflow​

.github/workflows/atmos.yaml

jobs:
  affected:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Upload affected stacks
        run: atmos describe affected --upload

Pro Configuration

Configure workspace ID, authentication, payload chunking, and drift detection in your atmos.yaml.

Authentication​

Atmos Pro uses GitHub OIDC token exchange for authentication. No API keys or static credentials are needed. When running in GitHub Actions with id-token: write permission, Atmos automatically requests an OIDC token and exchanges it for a short-lived Atmos Pro bearer token.

The only configuration required is your workspace_id, which identifies your organization's workspace. This value is not a secret and is safe to commit to version control.

atmos.yaml

settings:
  pro:
    workspace_id: "your-workspace-id"

Features​

Affected Stacks​

Upload the results of atmos describe affected to Atmos Pro for visibility into what changed on each pull request. Atmos Pro correlates uploads with GitHub webhooks to show affected components directly in your PR workflow.

shell

atmos describe affected --upload

Component Instances​

Upload a complete inventory of all component instances across all stacks. Atmos Pro uses this to track what is deployed, where, and with what settings — across every repository in your organization.

shell

atmos list instances --upload

Stack Locking​

Prevent concurrent modifications to the same stack. Lock before apply, unlock after — Atmos Pro tracks who holds the lock and when it was acquired.

shell

atmos pro lock vpc -s prod-use1
atmos terraform apply vpc -s prod-use1
atmos pro unlock vpc -s prod-use1

Drift Detection​

Track Terraform plan results to detect infrastructure drift. When --upload-status is enabled, Atmos uploads the plan exit code so Atmos Pro can identify stacks that have drifted from their desired state and trigger remediation workflows.

shell

atmos terraform plan vpc -s prod-use1 --upload-status

Commands​

atmos describe affected --upload
Upload affected components and stacks to Atmos Pro for PR correlation.
atmos list instances --upload
Upload a complete inventory of component instances to Atmos Pro.
atmos pro lock
Lock a stack to prevent concurrent modifications.
atmos pro unlock
Unlock a previously locked stack.
atmos terraform plan --upload-status
Upload plan results for drift detection.

Environment Variables​

ATMOS_PRO_WORKSPACE_ID
Workspace identifier for OIDC authentication. Not a secret. Maps to settings.pro.workspace_id.
ATMOS_PRO_BASE_URL
Override the Atmos Pro API base URL. Maps to settings.pro.base_url.
ATMOS_PRO_ENDPOINT
Override the API endpoint path. Maps to settings.pro.endpoint.
ATMOS_PRO_TOKEN
Internal runtime token from OIDC exchange (advanced/internal). Do not set this manually; configure settings.pro.workspace_id and GitHub Actions id-token: write instead.

Troubleshooting​

OIDC Authentication Failures​

If --upload fails with an authentication error:

  1. Verify your workflow has id-token: write permission
  2. Confirm ATMOS_PRO_WORKSPACE_ID is set to the correct workspace
  3. Check that the Atmos Pro GitHub App is installed on your repository

Upload Access Denied (403)​

If the upload succeeds authentication but returns a 403:

  1. Verify the repository has been imported into your Atmos Pro workspace
  2. Check repository permissions in your Atmos Pro workspace settings
  • Pro Configuration - Full configuration reference for settings.pro
  • Auth - Configure OIDC authentication
  • Native CI - CI/CD integration for GitHub Actions