Upload Instances
Configure the GitHub Actions workflow that uploads your component inventory ("instances") to Atmos Pro. This is what populates your Stacks and Instances views and powers drift detection.
Atmos Pro displays your stacks and component instances based on inventory that your CI uploads. Atmos Pro has read access to your repository, but it cannot execute Atmos itself — Atmos has to run to deep-merge your stack configurations and evaluate YAML functions, which requires your dependencies and credentials. So a workflow in your repository runs
atmos list instances --upload and sends the resulting inventory back to Atmos Pro.Once this workflow has run successfully, your Stacks and Instances pages populate, and drift detection has the inventory it needs to schedule periodic plans.
Create the following workflow file in your repository. It runs on every push to your default branch (shown as
main below — replace if your repo uses master or trunk), on a daily schedule, and can also be triggered manually. The workflow is not dispatched by Atmos Pro — it runs on its own GitHub Actions triggers.name: 👽 Atmos Pro Upload Instances
run-name: Upload Instances
on:
push:
branches:
- main # replace with your repository's default branch if different
schedule:
- cron: "0 0 * * *"
workflow_dispatch:
concurrency:
group: ${{ github.workflow }}
cancel-in-progress: false
permissions:
id-token: write
contents: read
checks: write
statuses: write
jobs:
atmos-list-instances:
name: Upload Instances
runs-on:
- "ubuntu-latest"
container:
image: ghcr.io/cloudposse/atmos:${{ vars.ATMOS_VERSION }}
defaults:
run:
shell: bash
steps:
- name: Checkout
uses: actions/checkout@v6
with:
fetch-depth: 0
- name: Configure Git Safe Directory
run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
- name: Upload instances to Atmos Pro
env:
ATMOS_PRO_WORKSPACE_ID: ${{ vars.ATMOS_PRO_WORKSPACE_ID }}
ATMOS_PROFILE: github
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
atmos list instances --uploadThe
ATMOS_VERSION GitHub Actions variable should be set to a version without the v prefix (e.g.,
1.175.0, not v1.x.x), since Docker image tags do not use the v prefix.- The
pushtrigger runs on every push to your default branch, ensuring your inventory is updated immediately after merges. - The
scheduletrigger runs daily at midnight UTC to keep your inventory current even when nothing has merged. workflow_dispatchlets you run the workflow manually for testing or on-demand discovery.atmos list instances --uploaddiscovers all deployed component instances and reports them to Atmos Pro.
The workflow authenticates to Atmos Pro using GitHub OIDC — no long-lived API tokens required. Cloud credentials are handled by your Atmos Auth Profile, the same profile used by your plan and apply workflows.
After the workflow runs successfully:
- 1Open the Stacks page in Atmos Pro — your stacks and components should appear, organized by repository.
- 2Open the Instances page — each component/stack pair (an "instance") will be listed with its drift status, ready for drift detection scheduling.
If the page is still empty, check the workflow run logs for the
Upload instances to Atmos Pro step. Common issues:ATMOS_PRO_WORKSPACE_IDnot set in repository or organization variables.- The workflow runs on a branch that does not match the
pushbranches filter. - Cloud authentication isn't configured — atmos needs cloud credentials to read Terraform state and discover deployed instances.
Once instances are uploading, configure drift detection so Atmos Pro periodically checks for divergence between your code and live infrastructure.
Configure Drift Detection