Configure Drift Detection
Set up automated drift detection to identify and remediate infrastructure changes that diverge from your Atmos configuration.
Drift detection has two parts: configuring your stack config to define which workflows to run, and configuring Atmos Pro to schedule when drift detection runs.
How it works
This tells Atmos which GitHub Actions workflows to dispatch for detecting and remediating drift. Add this to your Atmos Pro mixin:
drift-detection-wf-config: &drift-detection-wf-config
atmos-terraform-plan.yaml:
inputs:
component: "{{ .atmos_component }}"
stack: "{{ .atmos_stack }}"
upload: "true"
apply-wf-config: &apply-wf-config
atmos-terraform-apply.yaml:
inputs:
component: "{{ .atmos_component }}"
stack: "{{ .atmos_stack }}"
github_environment: "{{ .vars.tenant }}-{{ .vars.stage }}"
settings:
pro:
drift_detection:
enabled: true
detect:
workflows: *drift-detection-wf-config
remediate:
workflows: *apply-wf-configThe
detect section configures plan workflows with upload: "true" so results are reported to Atmos Pro. The remediate section configures apply workflows to automatically fix drift when you choose to remediate.Use descriptive workflow filenames that include command keywords (e.g.,
atmos-terraform-plan.yaml for detection,
atmos-terraform-apply.yaml for remediation). Atmos Pro uses the filename to determine the command type for each
deployment. See Workflow Naming Conventions.Create a GitHub Actions workflow that discovers all deployed instances and uploads them to Atmos Pro. This workflow runs on push to
main, on a daily schedule, and can also be triggered manually.name: 👽 Atmos Pro Upload Instances
run-name: Upload Instances
on:
push:
branches:
- main
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: List instances and upload 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 --uploadKey aspects of this workflow:
- The
pushtrigger runs on every push tomain, ensuring your instance inventory is updated immediately after merges - The
scheduletrigger runs daily at midnight UTC to keep your instance inventory current workflow_dispatchallows manual triggering for testing or on-demand discovery- Cloud credentials are handled automatically by Atmos Auth Profiles—no need for separate credential configuration steps
atmos list instances --uploaddiscovers all deployed component instances and reports them to Atmos Pro
The list instances workflow needs to read Terraform state to discover deployed infrastructure. Cloud authentication is handled by your Atmos Auth Profile, which configures OIDC between GitHub Actions and your cloud provider. This is the same auth profile used by your plan and apply workflows.
Configure Cloud Authentication
Once your stack config and workflows are in place, configure when drift detection runs in the Atmos Pro dashboard. This is done per-repository in the repository settings.
Drift Detection Schedules
Automated schedules for acme-org/infra
Daily at 9:00 AM
Created by Erik Osterman on Mar 15, 2026
Max Concurrency:
UnlimitedSchedule (America/New_York):
0 9 * * *Enabled
Weekly on Monday at 6:00 PM
Created by Jane Smith on Mar 10, 2026
Max Concurrency:
10Schedule (America/New_York):
0 18 * * 1Disabled
Preview Only
In the Atmos Pro dashboard, navigate to your repository and open the settings panel. From there you can:
- Add schedules with cron expressions or quick presets (daily, weekly, monthly, every N hours)
- Set a timezone so schedules run at the right local time
- Limit concurrency to control how many drift detection workflows run simultaneously
- Enable or disable individual schedules without deleting them
- Trigger drift detection manually from the repository toolbar for on-demand checks
Ready to detect drift?
Now that drift detection is configured, explore example workflows or learn more about how drift detection works under the hood.