atmos-pro

name	atmos-pro
description	Atmos Pro setup and workflows: settings.pro, GitHub OIDC, affected and inventory uploads, stack locks, pro commit, workflow dispatch, merge queues, and drift detection
metadata	{"copyright":"Copyright Cloud Posse, LLC 2026","version":"1.0.0","category":"ci-automation"}

Atmos Pro

Use this skill when configuring or debugging Atmos Pro, including CI uploads, workflow dispatch, stack locking, GitHub App commits, merge queues, and drift detection.

Atmos Pro is the control plane for visibility and coordination. Atmos CLI remains the execution layer for plans, applies, deploys, auth, toolchains, and stack resolution.

Related Skills

Need	Load
GitHub Actions job structure and Native CI	atmos-ci
atmos/pro provider and github/sts integration	atmos-auth
Managed Git repositories and signed/pushed commits	atmos-git
Migrating old drift/action patterns	atmos-modernization

Minimal Setup

Configure the workspace ID in atmos.yaml or ATMOS_PRO_WORKSPACE_ID. It is not a secret.

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

In GitHub Actions, grant OIDC permission. Do not use static API keys for normal GitHub Actions workflows.

permissions:
  id-token: write
  contents: read

Atmos Pro exchanges the GitHub Actions OIDC token for a short-lived bearer token. The OIDC request URL/token are normally supplied by GitHub automatically.

Core Commands

Command	Purpose
atmos describe affected --upload	Upload affected stacks/components for PR and merge-queue correlation
atmos list instances --upload	Upload full component instance inventory
atmos terraform plan <component> -s <stack> --upload-status	Upload raw plan status for drift detection
atmos pro lock --component <component> --stack <stack>	Lock a stack/component before mutation
atmos pro unlock --component <component> --stack <stack>	Release a stack/component lock
atmos pro commit -m "<message>" --all	Commit CI-generated changes through the Atmos Pro GitHub App

atmos pro commit is for workflows that need committed changes to trigger follow-on CI. Commits created with GITHUB_TOKEN do not trigger subsequent GitHub Actions workflows; commits created by the Atmos Pro GitHub App do.

Workflow Dispatch

Atmos Pro reads settings.pro from uploaded stack/component payloads and dispatches GitHub workflows server-side for matching repository events.

settings:
  pro:
    enabled: true
    pull_request:
      synchronize:
        workflows:
          atmos-terraform-plan.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
      merged:
        workflows:
          atmos-terraform-apply.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
    merge_group:
      checks_requested:
        workflows:
          atmos-terraform-plan.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"

Use pull_request.synchronize for plan-on-change. Use pull_request.merged for the conventional apply workflow. Configure merge_group.checks_requested explicitly for GitHub merge queues rather than relying on fallback inference.

Drift Detection

Atmos Pro is the standard product path for drift detection. Do not recommend hand-rolled scheduled GitHub Actions or deprecated drift wrapper actions for new projects.

Enable drift detection per stack/component:

settings:
  pro:
    enabled: true
    drift_detection:
      enabled: true

Effective drift detection also requires the instance to be Pro-enabled. metadata.enabled: false or settings.pro.enabled: false disables drift dispatch regardless of settings.pro.drift_detection.enabled.

Upload plan status from the workflow that Atmos Pro dispatches:

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

Atmos Pro interprets plan/apply status server-side and coordinates drift visibility and remediation.

GitHub STS

For private GitHub modules, vendoring, component source, or remote import, configure the atmos/pro auth provider and github/sts integration in the atmos-auth skill. This lets Atmos Pro mint short-lived GitHub App installation tokens in CI without storing long-lived tokens.

Troubleshooting

• If uploads fail authentication, verify id-token: write, settings.pro.workspace_id or ATMOS_PRO_WORKSPACE_ID, and that the Atmos Pro GitHub App is installed.
• If uploads return 403, verify the repository is imported into the Atmos Pro workspace.
• If merge queue checks do not resolve, verify merge_group.checks_requested and that atmos describe affected --upload runs on merge_group events.
• If drift is not dispatched, verify settings.pro.enabled, settings.pro.drift_detection.enabled, and that the instance appears in atmos list instances --upload.