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

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

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

```bash
atmos pro install
```

Preview the generated changes before writing files:

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

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

**File:** `atmos.yaml`

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

### 2. Add Workflow Permissions

**File:** `.github/workflows/atmos.yaml`

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

### 3. Upload Affected Stacks from Your Workflow

**File:** `.github/workflows/atmos.yaml`

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

**File:** `atmos.yaml`

```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`](/cli/commands/pro/install)**
  Scaffold workflows, auth profiles, and configuration to connect a repository to Atmos Pro.
- **[`atmos describe affected --upload`](/cli/commands/describe/affected)**
  Upload affected components and stacks to Atmos Pro for PR correlation.
- **[`atmos list instances --upload`](/cli/commands/list/list-instances)**
  Upload a complete inventory of component instances to Atmos Pro.
- **[`atmos pro lock`](/cli/commands/pro/lock)**
  Lock a stack to prevent concurrent modifications.
- **[`atmos pro unlock`](/cli/commands/pro/unlock)**
  Unlock a previously locked stack.
- **[`atmos terraform plan --upload-status`](/cli/commands/terraform/plan)**
  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](/cli/configuration/settings/pro) - Full configuration reference for `settings.pro`
- [Auth](/stacks/auth) - Configure OIDC authentication
- [Native CI](/ci) - CI/CD integration for GitHub Actions