Skip to content

Experiments ​

Experimental features may change or be removed before becoming stable. Read the feature's documentation before using it.

Server opt-in ​

The experiments server setting grants permission to use experimental features. It is empty by default and read at startup. An experiment's HTTP routes are unavailable without its permission. Its own settings still control authentication and activation.

Atlantis refuses to start when an experimental feature's settings are enabled without the required permission or prerequisites. Errors name the setting, explain how to fix it, and link to this page. These checks apply to command-line flags, environment variables, and YAML configuration.

Use a command-line flag:

sh
atlantis server --experiments=api,drift-detection

Or an environment variable:

sh
ATLANTIS_EXPERIMENTS=api,drift-detection atlantis server

Or a YAML list in the server configuration file:

yaml
experiments:
  - api
  - drift-detection

Flags and environment variables accept comma-separated names. Repeating --experiments appends names. Flags override environment variables, which override the configuration file. Lists from different sources are not combined. --experiments= clears the list.

Names are lowercase and match exactly. Unknown names, wildcard values, all, and empty list entries prevent startup. Duplicate names have no additional effect. Repository atlantis.yaml files cannot grant experiment permissions.

Feature status ​

FeatureExperiment nameStageReleasesAvailabilityDesignTracking
APIapiExperimentalPlan/apply: v0.19.8+. Experiment gate: unreleased (Main only).Requires api; authenticated commands also require api-secretADR 0002API development #6162
Drift detectiondrift-detectionExperimentalLegacy API: v0.45.0+. Experiment gate: unreleased (Main only).Requires drift-detection, api-secret, and drift enable flagsADR 0002Development #7033

The supported names are api and drift-detection. Each permits its own route group and does not grant the other permission. No current release tag contains this setting.

Both experiments share ADR 0002, but have separate tracking issues and graduation criteria. Graduating either one does not make the other stable.

Upgrading existing alpha features ​

New permissions required

Existing API and drift installations must add the matching experiment names when upgrading to a release containing this gate. An existing api-secret or enabled drift flag without permission now prevents startup. Routes without permission return HTTP 404, including the previously public lock-listing route.

For an installation using both API commands and drift detection:

yaml
experiments:
  - api
  - drift-detection
api-secret: replace-with-your-existing-secret
enable-drift-detection: true

Keep enable-drift-remediation enabled only if you intend to permit destructive remediation apply. For a drift-only installation, omit api; drift routes remain available while command and lock routes stay disabled. The shared api-secret is permitted by either experiment.

Before rolling back to a binary that predates --experiments, remove the experiments setting from flags, environment variables, and YAML. Older binaries continue to use their legacy API and drift settings; follow that release's recovery guidance.

API ​

The api experiment covers the command and lock endpoints, including POST /api/plan, POST /api/apply, and GET /api/locks. Drift detection, remediation, and their endpoints belong to the separate drift detection experiment.

Add api to experiments to permit command and lock routes. To use authenticated command endpoints, configure api-secret and send its value in X-Atlantis-Token. Permission alone does not configure authentication or enable command execution.

Request and response fields, error handling, supported providers, and non-PR execution remain experimental. Command and lock responses currently use legacy top-level bodies; drift endpoints use a different envelope. See the API documentation for endpoint-specific behavior and limitations.

To disable all command and lock routes, remove api from experiments and restart. Remove api-secret too unless a permitted drift installation still needs it. These routes return HTTP 404 without permission. When api is permitted but no secret is configured, the existing read-only lock listing remains available; command requests require a secret.

API graduation checklist ​

  • [x] Require API permission for command and lock routes and reject settings without permission at startup. Evidence: configuration and route tests in #7030.
  • [ ] Review the request/response contract, error serialization, HTTP statuses, and compatibility of legacy response bodies against the command response tests.
  • [ ] Verify authentication, repository/team authorization, and plan/apply requirements for PR and non-PR requests against the API controller tests.
  • [ ] Verify concurrent request isolation, lock cleanup, and shutdown behavior against the API controller tests; resolve the contract for lock cleanup #6956 and shutdown #6934.
  • [ ] Verify supported-provider documentation and enable, disable, upgrade, and rollback instructions against the API documentation and target release.
  • [ ] Record the API graduation decision and first stable release in API tracker #6162.

Drift detection ​

Add drift-detection to experiments, configure api-secret, and enable enable-drift-detection. Missing permission or authentication configuration prevents startup when detection is enabled. Drift remediation apply additionally requires enable-drift-remediation. See the drift API documentation for configuration and limitations.

To disable drift detection and remediation, disable both enable flags, remove drift-detection from experiments, and restart. Keep api-secret only if the api experiment still needs it. Leaving a drift flag enabled after removing its permission prevents startup.

Results currently use in-memory storage and are lost on restart. Drift detection runs the configured plan lifecycle, including hooks and custom steps. Remediation apply requires its own enable flag and still enforces repository apply requirements. See the API documentation for request formats and limits.

Drift detection graduation checklist ​

  • [x] Require drift permission for drift routes and reject enabled drift/remediation flags without permission at startup. Evidence: configuration and route tests in #7030.
  • [ ] Verify drift classification, project/ref/workspace identity, and partial-failure behavior against the drift controller tests.
  • [ ] Review drift detection/status, remediation/history, and webhook contracts against the drift controller tests and drift API documentation.
  • [ ] Verify persistence and restart behavior against the drift storage tests, and document the supported retention policy.
  • [ ] Review remediation authorization and execution requirements against the remediation tests.
  • [ ] Verify enable, disable, upgrade, and rollback instructions with the target release.
  • [ ] Record the graduation decision and first stable release in development tracker #7033.

See the feature lifecycle ADR for the lifecycle policy and graduation requirements.

Copyright Atlantis a Series of LF Projects, LLC. For website terms of use, trademark policy and other project policies please see LF Projects, LLC Policies.