Stategraph

Stategraph replaces Terraform’s flat state file with a real database. Terrateam can use Stategraph as its execution engine, giving you faster plans, parallel execution, and structured visibility into your infrastructure.

Note

The Terrateam Stategraph integration requires a Stategraph server you operate. Terrateam does not run Stategraph for you in this version.

Prerequisites

Before enabling the Stategraph engine in Terrateam, you need:

1. A Stategraph server running and reachable from your Terrateam runners. Self-hosted instructions are at stategraph.com/docs.
2. A Stategraph API key with permission to read and write the states you’ll manage with Terrateam.
3. The Stategraph CLI installed locally (for one-time onboarding):

curl -fsSL https://get.stategraph.com/install.sh | sh

The Terrateam runner image already includes the CLI, so you only need to install it on the developer machine you use for the initial stategraph states create or stategraph import tf step.

Onboarding a directory

Each Terrateam dirspace (a directory with optional workspace) needs to be onboarded into Stategraph once before its first Terrateam run. From a developer machine with the stategraph CLI installed and STATEGRAPH_API_BASE / STATEGRAPH_API_KEY / STATEGRAPH_TENANT_ID exported:

1. Change into the directory containing your *.tf files.

2. If you do not yet have a terraform.tfstate for this directory, create a fresh Stategraph state:

   stategraph states create --name my-app

   If you already have a terraform.tfstate, import it instead:

   stategraph import tf --name my-app terraform.tfstate

3. Both commands write a stategraph.json file in the current directory. Commit this file to your repository alongside your Terraform code.

4. Repeat for each directory you want Terrateam to manage with Stategraph.

Enabling the Stategraph engine

Once stategraph.json is committed in each dirspace, enable the engine in .terrateam/config.yml:

engine:
  name: stategraph

You can optionally pin the CLI version:

engine:
  name: stategraph
  version: '1.2.1'

By default Stategraph wraps Terraform. To wrap OpenTofu instead, set tf_cmd and tf_version:

engine:
  name: stategraph
  tf_cmd: tofu
  tf_version: '1.7.0'

Required workflow secrets

The Terrateam runner needs three environment variables. Set these as secrets in your runner environment (GitHub Actions secrets, GitLab CI variables, or your self-hosted runner config):

Variable	Purpose
STATEGRAPH_API_BASE	URL of your Stategraph server, e.g. https://stategraph.example.com
STATEGRAPH_API_KEY	API key with permission to plan and apply against the relevant states
STATEGRAPH_TENANT_ID	The Stategraph tenant UUID. Run stategraph info to look it up.

All three are required. Plan and apply will fail at preflight if any are missing.

Running plan and apply

Once configured, use Terrateam commands normally. The runner shells out to stategraph tf plan and stategraph tf apply instead of terraform.

1. Open a pull request that touches a directory configured with engine: stategraph.

2. Terrateam runs a plan and comments on the pull request with the diff.

3. Review the plan, get any required approvals, and comment terrateam apply.

4. Terrateam runs an apply against your Stategraph server. The state changes are persisted in the Stategraph database.

Why Stategraph

• Faster plans on large repositories. Stategraph runs against a much smaller working set than a full Terraform plan.
• Parallel execution. Independent root modules can plan and apply concurrently against the same Stategraph server.
• Structured visibility. State lives in a real database. Query it with MQL to discover relationships, blast radius, drift, and gaps in your infrastructure.

See stategraph.com for the full product story.