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.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.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.

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@v4

      - 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