How it works

Stategraph runs a change to your cloud in one of two ways: Orchestration runs it from a pull request, and the stategraph CLI runs it with Infrastructure as a Database.

The pull request flow

Orchestration in 4 minutes. Watch on YouTube.
  1. You open, update, or comment on a pull request.
  2. Orchestration finds the directories that the change touches. You can set which files count.
  3. Your CI runner plans each directory, as if the pull request were merged.
  4. Orchestration posts the plan on the pull request.
  5. Your policy checks and a cost estimate run with the plan. A failed check can block the apply until someone approves it.
  6. You comment stategraph apply, or you merge, if you turned on apply after merge.
  7. Orchestration applies the plan that you reviewed, and locks those directories until the pull request merges.
  • If another pull request changes the same directories first, the apply stops and asks for a new plan.
  • Before a stategraph apply runs, your rules must pass, for example approvals.
  • With Enterprise, you can also control who can run each command.

Infrastructure as a Database

Infrastructure as a Database in 3 minutes. Watch on YouTube.
  1. You run stategraph plan or stategraph apply. In a pull request, Orchestration can do this for you.
  2. The CLI sends your Terraform code and the change to the server.
  3. The server records the change and returns only the code that the change needs: the changed resources, what they depend on, and what depends on them.
  4. The CLI runs Terraform or OpenTofu on it, with your local credentials, and reports the result to the server.
  5. The CLI shows the diff, the errors, or a summary.
  • The server keeps your state as a graph in PostgreSQL. It does not run your plans and applies.
  • Stategraph locks single resources, not the whole state. Changes to different resources run at the same time. If two changes touch the same resource, the later one fails.

Where each part runs

  • Stategraph runs on Stategraph Cloud, or on your own Docker Compose, Kubernetes, Amazon ECS, or Google Cloud Run deployment of the Enterprise build: see Self-hosting. It stores your states, transactions, users, and tenants, and serves the console and the API. The open-source edition of Orchestration runs with Docker Compose: see Self-hosted Open Source.
  • Plans and applies run on your GitHub Actions or GitLab CI runners. The stategraph CLI runs there or on your machine.
  • With Orchestration, you can query runs, pull requests, drift schedules, and more with SQL in your tenant.

Next steps