Skip to main content

Atmos Pro

Configure Atmos Pro integration for stack locking, status reporting, and workspace management across your organization.

Overview​

Atmos Pro provides centralized management capabilities for teams using Atmos at scale:

  • Stack Locking — Prevent concurrent modifications to the same stack
  • Status Reporting — Track deployment status and history
  • Workspace Management — Organize teams and projects

Configuration​

The only required setting is your workspace_id. All other settings have sensible defaults and can be left unset.

atmos.yaml
settings:
  pro:
    workspace_id: "your-workspace-id"

Configuration Reference​

settings.pro.enabled

Master switch for Atmos Pro on a component or stack. When atmos list instances --upload sends the inventory to Atmos Pro, this value controls whether the instance is tracked as active or shown as disabled.

Atmos collapses an enabled hierarchy before upload, so an outer disable always wins:

metadata.enabled  >  settings.pro.enabled  >  settings.pro.drift_detection.enabled

Disabling a component with metadata.enabled: false forces settings.pro.enabled (and therefore settings.pro.drift_detection.enabled) off in the uploaded payload — a disabled component is never dispatched for drift detection or workflow runs, regardless of its pro settings.

  • Type: boolean
  • Default: true (when a settings.pro block is present)
settings.pro.base_url

Base URL for the Atmos Pro API.

  • Type: string
  • Default: https://app.cloudposse.com
  • Environment Variable: ATMOS_PRO_BASE_URL
settings.pro.endpoint

API endpoint path appended to the base URL.

  • Type: string
  • Default: api/v1
  • Environment Variable: ATMOS_PRO_ENDPOINT
settings.pro.workspace_id

Atmos Pro workspace identifier. Required for authentication. This value is not a secret and is safe to commit to version control.

  • Type: string
  • Default: (none)
  • Environment Variable: ATMOS_PRO_WORKSPACE_ID
settings.pro.token

Bearer token for Atmos Pro API authentication. Atmos Pro does not issue API keys or personal access tokens — the only way to obtain a bearer token is by performing an OIDC token exchange against the Atmos Pro API. This is intended for advanced integrations outside of GitHub Actions.

  • Type: string
  • Default: (none)
  • Environment Variable: ATMOS_PRO_TOKEN
settings.pro.max_payload_bytes

Maximum payload size (in bytes) before Atmos automatically chunks upload requests to Atmos Pro. When atmos describe affected --upload or atmos list instances --upload produces a payload larger than this threshold, it is split into multiple smaller requests with batch metadata for server-side reassembly.

  • Type: integer
  • Default: 4194304 (4 MB)
settings.pro.exec.sync_timeout

How long Atmos waits for command-execution metadata delivery to Atmos Pro to be confirmed for the small set of commands that report synchronously (terraform plan, terraform apply, describe affected). Execution-metadata upload only happens automatically when Atmos detects it is running in a recognized CI environment and Atmos Pro is configured — there is no separate opt-in/opt-out flag, and unsupported or unrecognized CI environments never initiate uploads. This setting only lengthens the wait: values below the 10-second default are clamped up to 10 seconds rather than allowed to shorten it. All other commands report asynchronously with a short, fixed, non-configurable best-effort flush and never block on this setting.

  • Type: Go duration string (e.g. 10s, 20s, 1m)
  • Default: 10s
  • Environment Variable: ATMOS_PRO_EXEC_SYNC_TIMEOUT
settings.pro.github_oidc.request_url

GitHub Actions OIDC token request URL. Automatically set in GitHub Actions via the ACTIONS_ID_TOKEN_REQUEST_URL environment variable.

  • Type: string
settings.pro.github_oidc.request_token

GitHub Actions OIDC request token. Automatically set in GitHub Actions via the ACTIONS_ID_TOKEN_REQUEST_TOKEN environment variable.

  • Type: string

Environment Variables​

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_WORKSPACE_ID
Workspace identifier for authentication. Not a secret. Maps to settings.pro.workspace_id.
ATMOS_PRO_TOKEN
Bearer token obtained via OIDC token exchange (advanced). Maps to settings.pro.token.
ATMOS_PRO_RUN_ID
CI/CD run identifier. Set automatically in CI environments for tracking.
ATMOS_PRO_EXEC_SYNC_TIMEOUT
Wait ceiling for synchronous command-execution metadata delivery. Maps to settings.pro.exec.sync_timeout.

Authentication​

GitHub OIDC Token Exchange​

For GitHub Actions workflows, use OIDC token exchange for secure, token-less authentication. This is the recommended approach.

atmos.yaml
settings:
  pro:
    workspace_id: "your-workspace-id"
    github_oidc:
      request_url: !env ACTIONS_ID_TOKEN_REQUEST_URL
      request_token: !env ACTIONS_ID_TOKEN_REQUEST_TOKEN

In your GitHub Actions workflow:

name: Deploy Infrastructure
on: push

permissions:
  id-token: write  # Required for OIDC token request
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Deploy with Atmos
        run: |
          atmos pro lock vpc -s prod/us-east-1
          atmos terraform apply vpc -s prod/us-east-1
          atmos pro unlock vpc -s prod/us-east-1
Advanced: Bearer Token Authentication

Atmos Pro does not issue API keys or personal access tokens. The only way to obtain a bearer token is by performing your own OIDC token exchange against the Atmos Pro API. This is intended for advanced integrations outside of GitHub Actions, such as custom CI/CD pipelines that handle OIDC flows independently.

atmos.yaml
settings:
  pro:
    token: !env ATMOS_PRO_TOKEN

Pass the bearer token via environment variable:

export ATMOS_PRO_TOKEN="<bearer-token-from-oidc-exchange>"
atmos pro lock vpc -s prod/us-east-1

Event Integration​

Atmos Pro reacts to GitHub webhook events on your repositories and dispatches workflows on a per-stack, per-event basis. The contract is defined under settings.pro on each stack (or component): for every event activity you want Atmos Pro to handle, declare which workflow file to dispatch and which inputs to pass.

Atmos evaluates the stack’s templates and YAML functions, including workflow inputs, before uploading the resolved event configuration with atmos describe affected --upload or atmos list instances --upload. Atmos Pro reads that configuration server-side when the matching GitHub webhook arrives and dispatches the configured workflow against the correct SHA.

Supported events​

settings.pro.pull_request
Plan and apply workflows for pull-request lifecycle activities (opened, synchronize, reopened, merged).
settings.pro.release
Workflows triggered when a GitHub release is published.
settings.pro.drift_detection
Per-stack opt-in for drift detection. Atmos Pro periodically inspects enabled stacks and surfaces drift.
settings.pro.merge_group
Workflows for GitHub merge-queue checks. New in this release — see Merge Queue Support.

settings.pro.pull_request​

Configure workflow dispatch for pull-request activities. Each activity maps a GitHub PR action to a list of workflows to dispatch. The merged activity is synthesized by Atmos Pro from pull_request.closed events with merged: true and is the conventional place to wire your apply workflow.

stacks/mixins/atmos-pro.yaml
settings:
  pro:
    enabled: true
    pull_request:
      opened:
        workflows:
          atmos-terraform-plan.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
      synchronize:
        workflows:
          atmos-terraform-plan.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
      reopened:
        workflows:
          atmos-terraform-plan.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
      # `merged` is synthesized from pull_request.closed{merged:true}.
      merged:
        workflows:
          atmos-terraform-apply.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
settings.pro.pull_request.opened
Activity fired when a pull request is opened.
settings.pro.pull_request.synchronize
Activity fired when new commits are pushed to a pull request. This is the canonical "plan on every push" trigger and is also the fallback target for merge-queue checks (see Resolution order).
settings.pro.pull_request.reopened
Activity fired when a closed pull request is reopened.
settings.pro.pull_request.merged
Activity fired when a pull request is closed with merged: true. This is the conventional place to wire the apply workflow. Apply continues to fire here even when the PR is merged through a merge queue.

settings.pro.release​

Configure workflow dispatch for GitHub release activities.

atmos.yaml
settings:
  pro:
    enabled: true
    release:
      published:
        workflows:
          atmos-terraform-apply.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
settings.pro.release.published
Activity fired when a GitHub release is published. Typically wired to an apply workflow scoped to a production stack.

settings.pro.drift_detection​

Per-stack opt-in for Atmos Pro's drift detection. Configure once per stack (usually in _defaults.yaml) and override per environment as needed.

stacks/deploy/_defaults.yaml
settings:
  pro:
    enabled: true
    drift_detection:
      enabled: true
settings.pro.drift_detection.enabled

Enable Atmos Pro drift detection for this stack.

Effective drift detection also requires the component to be effectively Pro-enabled. An outer metadata.enabled: false or settings.pro.enabled: false disables drift detection regardless of this value — Atmos collapses the hierarchy (metadata.enabled > pro.enabled > drift_detection.enabled) before upload so a disabled component is never dispatched for drift.

  • Type: boolean
  • Default: false

Merge Queue Support​

Atmos Pro reports check status on GitHub merge-queue synthetic commits the same way it does on regular pull-request commits. When a PR enters the merge queue, GitHub creates a synthetic merge commit on a temporary gh-readonly-queue/<base>/pr-<N>-<sha> branch and re-runs all required status checks against that new SHA. Atmos Pro creates an "Atmos Pro" check run on that synthetic SHA, watches for the configured workflow to complete, and concludes the check (success / failure / no-affected-stacks neutral). Comment updates are posted to the originating PR so the queue check resolution appears on the same thread.

NOTE:

Prerequisites. Full merge-queue support requires Atmos CLI ≥ 1.218.0. Earlier CLI versions still work for the empty-diff case (Atmos Pro concludes the check as "No affected stacks workflow detected"), but PRs that actually touch stacks will be reported incorrectly until the CLI is upgraded.

How it works​

  1. PR opened or synchronized → Atmos Pro dispatches pull_request.synchronize.workflows against the PR head SHA.
  2. PR added to the merge queue → GitHub creates a synthetic merge commit on gh-readonly-queue/<base>/pr-<N>-<sha>. Atmos Pro creates a check run on that synthetic SHA and dispatches the workflow resolved from merge_group (see below).
  3. Queue ultimately merges the PR → GitHub fires pull_request.closed with merged: true on the originating PR. The existing pull_request.merged.workflows (apply) flow runs unchanged. Apply does not fire on merge_group events.

Configure settings.pro.merge_group​

To get the right outcome on merge-queue synthetic commits, declare a merge_group block alongside pull_request and release and point it at the workflow you want dispatched in the queue. Workflow filenames are arbitrary — Atmos Pro has no way to tell from the filename whether a workflow plans, applies, or does something else — so the recommended pattern is to be explicit about which workflow runs in the queue rather than relying on Atmos Pro to infer one from your pull_request.synchronize config.

In most cases the queue should run the same plan workflow as pull_request.synchronize, optionally with stricter inputs (fail-on-drift, required approvals, etc.):

stacks/mixins/atmos-pro.yaml
settings:
  pro:
    enabled: true
    pull_request:
      synchronize:
        workflows:
          atmos-terraform-plan.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
    merge_group:
      checks_requested:
        workflows:
          atmos-terraform-plan.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
              # Example: stricter inputs in the queue.
              fail_on_drift: "true"
settings.pro.merge_group.checks_requested

Activity fired when GitHub requests checks on a merge-queue synthetic commit (the only meaningful merge_group activity for Atmos Pro). The workflows map has the same shape as pull_request.<activity>.workflows.

Resolution order​

When Atmos Pro receives a merge-queue trigger for a stack, it resolves the workflow to dispatch in this order:

  1. settings.pro.merge_group.checks_requested.workflows if defined — this is the recommended path.
  2. Otherwise, settings.pro.pull_request.synchronize.workflows is used as a backstop so existing customers do not regress when a queue is enabled. Because workflow filenames are arbitrary, this backstop can dispatch a workflow that is not appropriate for the queue (e.g. an apply step). Treat it as a transitional behavior, not a recommended configuration.
  3. Otherwise, no workflow is dispatched (same null behavior as a stack with no per-event configuration).

Schema notes​

  • merge_group is a sibling of pull_request / release / drift_detection, not nested under pull_request. The events fire on different SHAs and have a different action vocabulary, matching GitHub's webhook event model.
  • The only valid activity under merge_group today is checks_requested. GitHub also fires merge_group.destroyed, but Atmos Pro relies on its existing stale-uploads reconciler for cleanup, so users do not configure anything for it.

Migration note​

If you are enabling GitHub merge queue on a repository that already uses Atmos Pro, the right migration is to add a settings.pro.merge_group block to every stack mixin that already has settings.pro.pull_request. In most cases the queue should dispatch the same plan workflow as pull_request.synchronize — declare it explicitly so the queue's check outcome is deterministic and reviewable from your stack config rather than inferred from a backstop.

See also​

Workflow input templating​

Atmos resolves workflow inputs against the component’s template context while processing the stack, before uploading the workflow configuration to Atmos Pro. These are Atmos Go templates; GitHub evaluates its own ${{ inputs.runner }} expressions later, in the dispatched workflow.

  • {{ .atmos_component }} — the Atmos component instance name, such as cluster/prod
  • {{ .atmos_stack }} or {{ .stack }} — the stack name
  • {{ .vars.<name> }} — a value from the component’s vars
  • {{ .settings.<name> }} — a value from its settings
  • {{ .metadata.labels.runner }} — a value from its labels
  • {{ index .metadata.labels "cost-center" }} — a label whose key contains a hyphen

Use .atmos_component for the workflow’s component input. The shorter .component can identify the underlying implementation selected by metadata.component, which may be shared by several differently named instances.

The YAML functions also work in workflow inputs. For example, !labels runner ubuntu-latest reads one label and supplies a fallback when it is absent.

Choose a runner per component or stack​

Set a runner label on the component and pass it to the workflow:

stack.yaml
components:
  terraform:
    cluster:
      metadata:
        labels:
          runner: self-hosted-large
      settings:
        pro:
          pull_request:
            synchronize:
              workflows:
                atmos-terraform-plan.yaml:
                  inputs:
                    component: "{{ .atmos_component }}"
                    stack: "{{ .atmos_stack }}"
                    runner: "{{ .metadata.labels.runner }}"

In the GitHub workflow, add a runner dispatch input and use it on the job. These excerpts extend the workflow’s existing inputs and job steps:

.github/workflows/atmos-terraform-plan.yaml
on:
  workflow_dispatch:
    inputs:
      runner:
        description: Runner label
        type: string
        default: ubuntu-latest

jobs:
  atmos-plan:
    runs-on: "${{ inputs.runner }}"

Do the same in the apply workflow, and pass runner in its event configuration for merges, releases, and drift remediation. The selector must match an existing runner available to the repository; it does not create or size one. Workflows using job containers require a compatible Linux runner with Docker.

This selects one runner label. Putting the input in a one-element array does not split comma-separated labels. See GitHub’s runner syntax for selecting multiple labels.

For components without a runner label, supply a fallback with !labels:

runner: !labels runner ubuntu-latest

Alternatively, import a stack-wide label default. The template form requires the label to exist: GitHub’s input default cannot recover from an Atmos template error before dispatch. See metadata inheritance for sharing component labels; mapping a component with metadata.component alone does not inherit its labels.

Inspect the resolved runner with atmos describe component cluster -s <stack>. You can also select components by it using atmos list components --labels runner=self-hosted-large.

Execution metrics and runner sizing​

Starting with Atmos CLI v1.228.0, qualifying invocations in recognized CI environments automatically upload execution records when Atmos Pro credentials are configured. Records include elapsed time and, on supported platforms, CPU time and peak memory — combining the terraform/tofu subprocess tree (including provider plugins) with Atmos's own usage, so the numbers reflect what the run actually cost, not just the CLI wrapper's overhead.

CPU time is not peak CPU utilization, and the reported peak memory is the largest single process observed during the run (terraform, tofu, or one provider plugin) — not a simultaneous sum across every concurrently running process. If Terraform and two provider plugins each peak at 200 MB at the same moment, this reports roughly 200 MB, not 600 MB; treat it as a lower bound, not an exact whole-job figure, when choosing runner capacity. See Metrics for the local-display counterpart of these same numbers, and execution metadata for upload behavior and configuration.

Related Commands​