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.

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

The right onboarding path depends on how much of your Atmos and CI authentication setup is already in place. Choose the path that matches your current state.

1. Don't use Atmos

Start by setting up Atmos itself before you connect the repository to Atmos Pro. The fastest path is to create your first stacks, get your project structure in place, and make sure GitHub Actions is part of your workflow.

Start with Atmos

If this repository is not using Atmos yet, begin with the Quick Start and come back here once your stacks are configured.

Simple Quick StartProject Layout

2. Use Atmos but not OIDC

If the repository already uses Atmos, the next prerequisite for Atmos Pro is OIDC-based authentication in CI. Configure your cloud auth provider and the identities or stack auth settings that your workflows will use.

Set up OIDC

Atmos Pro relies on GitHub Actions OIDC token exchange. Configure cloud-side trust and Atmos auth first, then return here to install the Pro integration.

Auth ProvidersStack Auth

3. Use Atmos with OIDC

If your repository already uses Atmos and GitHub Actions OIDC is configured with your cloud provider, the fastest way to connect it to Atmos Pro is atmos pro install.

1. Install the Pro integration

atmos pro install

Preview the generated changes before writing files:

atmos pro install --dry-run

Install Atmos Pro

Use the installer for the fastest path to GitHub Actions workflows, auth profiles, and Atmos Pro configuration.

Command ReferenceConfiguration Reference

What the installer sets up

Once those prerequisites are in place, the installer scaffolds the repository-side pieces needed to connect to Atmos Pro:

• Workspace configuration in atmos.yaml
• GitHub Actions OIDC permissions for token exchange
• Workflow wiring for uploading affected stacks

It does not create the cloud-side OIDC trust relationships for you. Configure those first if your CI environment is not already using Atmos auth with OIDC.

Manual setup

If you need to configure the integration by hand, use the following steps. This assumes your Atmos project already exists and your CI authentication path is ready.

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@v6
      - name: Upload affected stacks
        run: atmos describe affected --upload

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 pro install

Scaffold workflows, auth profiles, and configuration to connect a repository to Atmos Pro.

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

Related

• Pro Configuration - Full configuration reference for settings.pro
• Auth - Configure OIDC authentication
• Native CI - CI/CD integration for GitHub Actions