Atlantis

Atlantis custom workflows let you replace the built-in Terraform commands with your own. Two run steps put Stategraph underneath your existing Atlantis setup: comments, applies-from-PR, and locks behave as before, while plans and applies execute through the Stategraph CLI and state lives in Stategraph.

Prerequisites

  • A running Atlantis server with the stategraph binary and OpenTofu on its PATH (build a derived image from your Atlantis base image, or bake both into a custom image)
  • Stategraph reachable from the Atlantis server, plus STATEGRAPH_API_BASE, STATEGRAPH_API_KEY, and STATEGRAPH_TENANT_ID set in the Atlantis server's environment
  • Your state imported once, with stategraph.json committed (see Setup)

Define the workflow

Server-side, in repos.yaml:

repos:
  - id: github.com/acme/infra
    workflow: stategraph

workflows:
  stategraph:
    plan:
      steps:
        - run: stategraph plan --out $PLANFILE
    apply:
      steps:
        - run: stategraph apply $PLANFILE

Or repo-side in atlantis.yaml, if your server sets allowed_overrides: [workflow] and allow_custom_workflows: true:

version: 3
projects:
  - dir: infra
    workflow: stategraph
workflows:
  stategraph:
    plan:
      steps:
        - run: stategraph plan --out $PLANFILE
    apply:
      steps:
        - run: stategraph apply $PLANFILE

$PLANFILE is where Atlantis expects the plan artifact: stategraph plan --out writes it there, and the apply step commits exactly that reviewed plan. The plan step's output — the Stategraph diff — is what Atlantis posts back to the pull request.

What changes, what doesn't

Atlantis still listens for atlantis plan and atlantis apply comments, still comments results on the PR, and still tracks which PR holds which project. Underneath, refresh, plan, and apply are scoped to the subgraph your change touches, and two PRs touching disjoint resources no longer contend for one state-file lock — a genuine overlap is rejected per resource at commit with the conflicting transaction id.

Atlantis's own working-directory locks remain project-level; they prevent two PRs from planning the same project directory simultaneously, which is about workspace hygiene rather than state. The state-level global lock is gone.

Limitations

  • Destroy is not supported through the CLI yet; keep atlantis destroy-style workflows on your existing path or run destroys locally.
  • The CLI must be on the Atlantis server's PATH before the first plan — there is no per-run install hook like other CI systems; use a derived image.

Next Steps