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 }}"
apply-wf-config: &apply-wf-config
atmos-terraform-apply.yaml:
inputs:
component: "{{ .atmos_component }}"
stack: "{{ .atmos_stack }}"
github_environment: "{{ .vars.stage }}"
settings:
pro:
drift_detection:
enabled: true
detect:
workflows: *drift-detection-wf-config
remediate:
workflows: *apply-wf-configThe
detect section configures the dedicated Atmos Pro plan workflow used for drift checks. The remediate section configures the dedicated Atmos Pro apply workflow used to fix drift when you choose to remediate. Both workflow files should run their Atmos commands with --upload so results are reported to Atmos Pro.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.Drift detection requires that Atmos Pro know about every deployed instance. A separate GitHub Actions workflow runs
atmos list instances --upload on every push to main and on a daily schedule to keep that inventory current.The full workflow YAML, configuration variables, and verification steps live on a dedicated page:
Configure the Upload Instances Workflow
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, open the settings panel, and switch to the Drift tab. From there you can:
- Verify drift after apply so successful apply and remediate runs dispatch a follow-up drift detection check for affected components
- 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
The Verify drift after apply setting is enabled by default for each repository. When it is enabled, a successful normal apply or drift remediation apply triggers a drift detection run for the same stack and component, as long as the component has a configured detection workflow.
This prevents stale drift from becoming permanent in the Drift view. Apply success means Terraform accepted the change, but drift status is only confirmed once the follow-up detection workflow reports its plan result. If a component does not have a detection workflow configured, Atmos Pro skips the verification run and keeps the apply-derived status instead of leaving the component in a checking state.
Repository owners and admins can turn this setting off from the Drift tab. When disabled, successful applies mark the component in sync and failed applies mark it errored without dispatching the follow-up verification run.
You can deep-link directly to the drift tab at
/repos/{owner}/{repo}/settings?tab=drift.Ready to detect drift?
Now that drift detection is configured, explore example workflows or learn more about how drift detection works under the hood.