# Stategraph > Stategraph is a database for your infrastructure. Plans run on the affected graph. Velocity, orchestration, security, compliance, cost, and inventory flow from one data model. Every documentation page is also available as Markdown by appending `.md` to its URL (e.g. `/docs/cli/transactions.md`). ## Get started ### Overview - [Documentation](https://stategraph.com/docs.md): Stategraph is infrastructure as code with a database underneath. Orchestration runs plans and applies in pull requests, and Infrastructure as a Database replaces the state file. - [How it works](https://stategraph.com/docs/get-started/how-it-works.md): Follow a change through Stategraph: the pull request flow in Orchestration, how Infrastructure as a Database runs it, and where each part runs. - [Core concepts](https://stategraph.com/docs/get-started/core-concepts.md): Learn the terms that Stategraph uses: tenants, runs, dirspaces, stacks, locks, tag queries, states, instances, and transactions. - [Editions and pricing](https://stategraph.com/docs/get-started/editions.md): Compare Stategraph Orchestration Open Source and Enterprise, Infrastructure as a Database, and the Stategraph Cloud plans, prices, and limits. - [Integrations](https://stategraph.com/docs/get-started/integrations.md): Connect Stategraph to your cloud providers, infrastructure as code tools, CI systems, and external tools, with a setup guide for each one. ### Quickstart - [Quickstart](https://stategraph.com/docs/get-started/quickstart.md): Choose how to start with Stategraph: Stategraph Cloud, self-hosting Open Source or Enterprise with Docker Compose, or a Terraform state import. - [Stategraph Cloud](https://stategraph.com/docs/get-started/quickstart/cloud.md): Sign up for Stategraph Cloud, connect GitHub or GitLab, and get your first plan and apply on a pull request. - [Self-hosted Open Source](https://stategraph.com/docs/get-started/quickstart/self-hosted-open-source.md): Run Stategraph Orchestration Open Source with Docker Compose, connect GitHub or GitLab, and get your first plan on a pull request. - [Self-hosted Enterprise](https://stategraph.com/docs/get-started/quickstart/self-hosted.md): Run the Stategraph Enterprise build with Docker Compose and a license key, connect GitHub or GitLab, and get your first plan on a pull request. - [Import your state](https://stategraph.com/docs/get-started/quickstart/import-state.md): Import a Terraform or OpenTofu state into Stategraph with the CLI, then run your first scoped plan and apply. ## Orchestration ### Introduction - [Stategraph Orchestration](https://stategraph.com/docs/orchestration.md): Stategraph Orchestration runs Terraform and OpenTofu from pull requests: automatic plans, policy checks, approvals, applies, and drift detection. ### Workflows - [Pull Request Workflow](https://stategraph.com/docs/orchestration/workflows.md): Stategraph Orchestration plans each pull request, posts plan comments and commit checks, applies the reviewed plan, and locks directories. - [Apply After Merge](https://stategraph.com/docs/orchestration/workflows/apply-after-merge.md): Apply infrastructure changes automatically when a pull request merges, with when_modified.autoapply, selective directories, and apply requirements. - [Rollbacks](https://stategraph.com/docs/orchestration/workflows/rollbacks.md): Revert an applied infrastructure change by reverting the pull request that introduced it, then reviewing and applying the resulting plan. - [Performance](https://stategraph.com/docs/orchestration/workflows/performance.md): Profile a slow Stategraph Orchestration run, then cut startup cost, run fewer directories, run them concurrently, and make each one cheaper. - [Commits That Move During a Run](https://stategraph.com/docs/orchestration/workflows/stale-runs.md): How Stategraph Orchestration handles a push or a merge while a plan or an apply runs, and what a stale result means for your pull request. #### Advanced patterns - [Multiple Environments](https://stategraph.com/docs/orchestration/workflows/advanced/multi-environment.md): Manage production, staging, and QA in one repository with separate directories, workspaces, or tfvars files, and target each with tag queries. - [Grouping Infrastructure with Stacks](https://stategraph.com/docs/orchestration/workflows/advanced/stacks.md): Group directories and workspaces into named stacks with plan_after, apply_after, modified_by, and auto_apply rules to build a deployment pipeline. - [Layered Runs](https://stategraph.com/docs/orchestration/workflows/advanced/layered-runs.md): Order plan and apply across dependent layers of infrastructure with depends_on, so each layer runs only after the layers it depends on have applied. - [Gitflow](https://stategraph.com/docs/orchestration/workflows/advanced/gitflow.md): Implement a Gitflow branching model with Stategraph Orchestration using destination branch tags, branch rules, and one workflow per branch. - [Tags and Tag Queries](https://stategraph.com/docs/orchestration/workflows/advanced/tag-system.md): Group directories and workspaces with tags, then target them with tag queries in workflows, access control, apply requirements, and commands. - [Locks and Concurrency](https://stategraph.com/docs/orchestration/workflows/advanced/lock-management.md): How Orchestration locks directories on apply and merge, when locks are released, how to unlock, and how to tune lock_policy per workflow. - [Choosing an Engine](https://stategraph.com/docs/orchestration/workflows/advanced/engine-setup.md): Choose the engine that runs plan and apply: Terraform, OpenTofu, the stategraph CLI, Terragrunt, Pulumi, CDKTF, or a custom command. - [Custom Plan and Apply Steps](https://stategraph.com/docs/orchestration/workflows/advanced/custom-commands.md): Extend plan and apply workflows with run, env, and oidc steps to add validation, security scanning, and notifications around Terraform operations. - [Custom Runners](https://stategraph.com/docs/orchestration/workflows/advanced/runs-on.md): Choose the GitHub Actions or GitLab CI runners that execute plan and apply with the runs_on workflow key, using runner labels or runner tags. - [Dynamic Configuration](https://stategraph.com/docs/orchestration/workflows/advanced/dynamic-configuration.md): Generate the repository configuration at runtime with config_builder, a script that reads the merged configuration and writes the final one. - [Terragrunt Config Builder](https://stategraph.com/docs/orchestration/workflows/advanced/terragrunt-config-builder.md): Discover every Terragrunt module in a monorepo with the bundled config builder script and generate depends_on ordering from dependency blocks. - [Custom File Discovery with Tree Builder](https://stategraph.com/docs/orchestration/workflows/advanced/tree-builder-setup.md): Replace Git file discovery with a tree_builder script that reports which files exist and which changed, for generated Terraform and custom rules. - [YAML Anchors](https://stategraph.com/docs/orchestration/workflows/advanced/yaml-anchors.md): Reuse engine settings, workflow steps, access policies, and apply requirements across your configuration with YAML anchors in the definitions section. - [GitHub Reusable Workflows](https://stategraph.com/docs/orchestration/workflows/advanced/github-reusable-workflows.md): Centralize the Orchestration GitHub Actions workflow in one repository and call it from every Terraform repository with a small workflow_call caller. ### Configuration - [Configuration](https://stategraph.com/docs/orchestration/configuration.md): Configure Stategraph Orchestration with the .stategraph/config.yml file: its main sections, and a link to each configuration reference page. - [Modules](https://stategraph.com/docs/orchestration/configuration/modules.md): Trigger plans in the directories that depend on a Terraform module, discover dependencies automatically, and clone modules from private repositories. - [Secrets and Variables](https://stategraph.com/docs/orchestration/configuration/variables.md): Pass secrets, environment variables, and .tfvars files to Terraform runs through GitHub secrets, GitLab CI/CD variables, hooks, and workflows. - [Environment Variables](https://stategraph.com/docs/orchestration/configuration/environment-variables.md): Use the environment variables that the runner sets in workflows and hooks, and define your own variables with env steps. - [CODEOWNERS](https://stategraph.com/docs/orchestration/configuration/codeowners.md): Block applies until the code owners your VCS requires have approved the pull request, using require_completed_reviews in apply requirements. ### Integrations #### Cloud providers ##### AWS - [AWS](https://stategraph.com/docs/orchestration/cloud-providers/aws.md): Connect Stategraph Orchestration to AWS with static IAM access keys or OpenID Connect, then run plan and apply against your AWS account. - [AWS OIDC](https://stategraph.com/docs/orchestration/cloud-providers/aws/oidc.md): Set up OpenID Connect between GitHub Actions and AWS so Stategraph Orchestration assumes an IAM role without storing long-lived access keys. - [AWS static credentials](https://stategraph.com/docs/orchestration/cloud-providers/aws/static-credentials.md): Create an IAM user with access keys and store them as GitHub secrets or GitLab CI/CD variables so Stategraph Orchestration can reach AWS. ##### GCP - [GCP](https://stategraph.com/docs/orchestration/cloud-providers/gcp.md): Connect Stategraph Orchestration to Google Cloud with a service account key or Workload Identity Federation, then plan and apply against your project. - [GCP OIDC](https://stategraph.com/docs/orchestration/cloud-providers/gcp/oidc.md): Set up Workload Identity Federation so Stategraph Orchestration impersonates a Google Cloud service account from GitHub Actions without a key file. - [GCP static credentials](https://stategraph.com/docs/orchestration/cloud-providers/gcp/static-credentials.md): Create a Google Cloud service account key and store it as a GitHub secret or GitLab CI/CD variable so Stategraph Orchestration can reach GCP. ##### Azure - [Azure](https://stategraph.com/docs/orchestration/cloud-providers/azure.md): Connect Stategraph Orchestration to Azure with a service principal secret or an Entra ID federated credential, then plan and apply changes. - [Azure OIDC](https://stategraph.com/docs/orchestration/cloud-providers/azure/oidc.md): Set up an Entra ID federated credential so Stategraph Orchestration authenticates to Azure from GitHub Actions without a client secret. - [Azure static credentials](https://stategraph.com/docs/orchestration/cloud-providers/azure/static-credentials.md): Create an Azure service principal with a client secret and store its values as GitHub secrets or GitLab CI/CD variables for Orchestration. - [Other providers](https://stategraph.com/docs/orchestration/cloud-providers/other.md): Give Stategraph Orchestration credentials for any Terraform provider by storing its access token as a repository secret or CI/CD variable. #### IaC tools - [Terraform](https://stategraph.com/docs/orchestration/iac-tools/terraform.md): Pin the Terraform CLI version Stategraph Orchestration runs, per directory, per workflow, or for the whole repository, and choose the engine. - [OpenTofu](https://stategraph.com/docs/orchestration/iac-tools/opentofu.md): Run OpenTofu as the engine for Stategraph Orchestration plans and applies, globally or per workflow, and switch between OpenTofu and Terraform. - [Terragrunt](https://stategraph.com/docs/orchestration/iac-tools/terragrunt.md): Run Terragrunt through Stategraph Orchestration. Set the engine, trigger runs on terragrunt.hcl changes, and auto-discover modules in large monorepos. - [Pulumi](https://stategraph.com/docs/orchestration/iac-tools/pulumi.md): Run Pulumi previews and updates through Stategraph Orchestration pull requests with the pulumi engine, runtime hooks, and stack directories. - [CDKTF](https://stategraph.com/docs/orchestration/iac-tools/cdktf.md): Run CDKTF stacks through Stategraph Orchestration. Enable the cdktf engine per directory, plan a stack by tag, and read runner environment variables. - [Migrating from Terraform Cloud](https://stategraph.com/docs/orchestration/iac-tools/terraform-cloud-migration.md): Move workspaces from Terraform Cloud to Stategraph: inventory, state in Infrastructure as a Database or a bucket, secrets, workflows, and validation. #### External tools - [Policy enforcement with OPA](https://stategraph.com/docs/orchestration/external-tools/opa.md): Enforce Rego policies on every Stategraph Orchestration plan with the conftest and opa workflow steps, custom policy directories, and approval gates. - [Cost Estimation in Pull Requests](https://stategraph.com/docs/orchestration/external-tools/infracost.md): Stategraph Orchestration adds an Infracost estimate to every plan comment, showing the monthly cost change of a pull request before it is applied. - [Webhooks](https://stategraph.com/docs/orchestration/external-tools/webhooks.md): Send HTTP requests to external systems from Stategraph Orchestration hooks and workflow steps, on success or failure, with run context in the payload. - [AI integrations](https://stategraph.com/docs/orchestration/external-tools/ai-integrations.md): Send plan and apply results from Stategraph Orchestration to an LLM in a post hook and post the summary or error analysis on the pull request. - [Installing packages](https://stategraph.com/docs/orchestration/external-tools/installing-packages.md): Install extra packages on the Stategraph Orchestration runner, globally with a pre hook or inside one workflow, using apt-get in run steps. ### Security and governance #### Security - [Security best practices](https://stategraph.com/docs/orchestration/security.md): Recommended practices for running Stategraph Orchestration in production. Isolate secrets, control who can plan and apply, and audit every change. - [Cloud credentials](https://stategraph.com/docs/orchestration/security/cloud-credentials.md): Authenticate Stategraph Orchestration runs to AWS, Azure, and GCP with OIDC, static credentials, or a custom credential script. - [Hardening AWS OIDC](https://stategraph.com/docs/orchestration/security/hardening-aws-oidc.md): Lock down the AWS IAM trust policy so that only workflow runs dispatched by Stategraph Orchestration can assume your cloud roles. - [GitHub Environments](https://stategraph.com/docs/orchestration/security/github-environments.md): Bind Stategraph Orchestration workflows to GitHub Environments so that each environment's secrets, variables, and protection rules apply to its runs. - [Private runners](https://stategraph.com/docs/orchestration/security/private-runners.md): Run Stategraph Orchestration plans and applies on self-hosted GitHub Actions runners or GitLab runners in your own network or cluster. - [Plan file storage](https://stategraph.com/docs/orchestration/security/plan-file-storage.md): Choose where Stategraph Orchestration keeps the plan file between plan and apply. Use the server, an S3 bucket, custom commands, or no storage. - [Self-signed certificates](https://stategraph.com/docs/orchestration/security/self-signed-certificates.md): Make Stategraph Orchestration runners and a self-hosted Stategraph server trust the certificates of your private certificate authority. - [Audit trail](https://stategraph.com/docs/orchestration/security/audit-trail.md): Query the history of every Stategraph Orchestration run by user, directory, and date, and trace state changes through the transaction timeline. #### Governance - [Role-Based Access Control](https://stategraph.com/docs/orchestration/governance/rbac.md): Control who can plan, apply, and override in Stategraph Orchestration with access control policies by user, team, repository role, and tag query. - [Gatekeeper](https://stategraph.com/docs/orchestration/governance/gatekeeper.md): Create manual approval gates in Stategraph Orchestration so authorized users can override failed security scans, policy checks, and validations. - [Drift Detection](https://stategraph.com/docs/orchestration/governance/drift-detection.md): Detect and reconcile infrastructure drift on a schedule with Stategraph Orchestration, open GitHub or GitLab issues, and track it in the console. - [Centralized Configuration](https://stategraph.com/docs/orchestration/governance/centralized-config.md): Manage Stategraph Orchestration configuration defaults, overrides, and forced configurations for every repository from one central repository. - [Feature Branch Configuration Overrides](https://stategraph.com/docs/orchestration/governance/config-overrides.md): Control which .stategraph/config.yml keys must come from the default branch and which feature branches may override with default_branch_overrides. ## Infrastructure as a Database ### Introduction - [Infrastructure as a Database](https://stategraph.com/docs/infrastructure-as-a-database.md): Infrastructure as a Database keeps your Terraform and OpenTofu state as a graph in PostgreSQL, with scoped plans, resource locks, and SQL. - [Setup](https://stategraph.com/docs/infrastructure-as-a-database/setup.md): Set up Infrastructure as a Database for a Terraform module. Create an API key, configure the CLI, add a state, and run your first plan and apply. - [Use with Orchestration](https://stategraph.com/docs/infrastructure-as-a-database/orchestration.md): Run Stategraph Orchestration plans and applies with Infrastructure as a Database: onboard directories, set the engine, and add runner secrets. ### Changes - [Transactions](https://stategraph.com/docs/infrastructure-as-a-database/transactions.md): Each Stategraph plan and apply runs in a transaction that goes through create, preview, a conflict check, and commit. - [Resource-Level Locking](https://stategraph.com/docs/infrastructure-as-a-database/resource-locking.md): Stategraph detects conflicts per resource, not per state, so concurrent transactions on one Terraform state stay safe. - [Multi-state transactions](https://stategraph.com/docs/infrastructure-as-a-database/multi-state.md): Plan and apply several Terraform states in one transaction: the states that a change reaches, or the directories you name. - [Refactoring](https://stategraph.com/docs/infrastructure-as-a-database/refactoring.md): Rename and move Terraform resources without state loss: a refactor session finds the moves and writes the moved blocks for you. ### Query and insights - [Query and insights](https://stategraph.com/docs/infrastructure-as-a-database/query.md): Browse, search, and query your Terraform inventory in the console or with SQL, and see the change history, blast radius, and dependencies. - [Query (SQL)](https://stategraph.com/docs/infrastructure-as-a-database/query/query.md): Query your Terraform infrastructure with SQL. Filter resources by attribute, aggregate counts, and analyze configurations in all states. - [Instances](https://stategraph.com/docs/infrastructure-as-a-database/query/instances.md): Browse the resource instances in all your Terraform states. Filter them, and inspect the attributes and dependencies of each one. - [Modules](https://stategraph.com/docs/infrastructure-as-a-database/query/modules.md): Browse the Terraform modules in your states and the resources in each module, and query module usage and structure with SQL. - [Resource Types](https://stategraph.com/docs/infrastructure-as-a-database/query/resource-types.md): See the resources in all your states grouped by type and provider, with counts for each type and SQL queries for type analysis. - [Gap Analysis](https://stategraph.com/docs/infrastructure-as-a-database/query/gap-analysis.md): Find the AWS and GCP resources that no Terraform state manages, and generate the Terraform code that brings them under management. - [Dashboards](https://stategraph.com/docs/infrastructure-as-a-database/query/dashboards.md): Build dashboards in the Stategraph console from saved SQL queries, filters, and charts, for quick access to views of your infrastructure. - [Dashboard metrics](https://stategraph.com/docs/infrastructure-as-a-database/query/dashboard-metrics.md): Learn what each metric on the console home page means, how Stategraph calculates it, and what to look for in your states. - [Timeline](https://stategraph.com/docs/infrastructure-as-a-database/query/timeline.md): See the transaction history of your Terraform states in the Timeline. Find who changed what and when, and inspect and tag changes. - [Search](https://stategraph.com/docs/infrastructure-as-a-database/query/search.md): Find resource instances in all your states by type, module, provider, address, or attribute value on the Search screen in Insights. - [Blast radius analysis](https://stategraph.com/docs/infrastructure-as-a-database/query/blast-radius.md): Find all resources that a change to one resource can affect, across linked states, before you make the change. - [Graph Explorer](https://stategraph.com/docs/infrastructure-as-a-database/query/graph-explorer.md): See one resource and every block that a change to it reaches as an interactive dependency graph, across modules and linked states. ### Cost - [Cost intelligence](https://stategraph.com/docs/infrastructure-as-a-database/cost.md): See what your Terraform state costs per resource, state, and tenant, see the cost delta of a plan, and compare the estimates with billed spend. - [Plan-time cost](https://stategraph.com/docs/infrastructure-as-a-database/cost/plan-time.md): See the cost of a Terraform change before you apply it: Stategraph shows the current cost, the planned cost, and the delta under the plan diff. - [State and resource cost](https://stategraph.com/docs/infrastructure-as-a-database/cost/state-cost.md): Get the cost of one Terraform state, read the cost of each resource and pricing component, refresh the estimate, and find coverage gaps. - [Cost attribution](https://stategraph.com/docs/infrastructure-as-a-database/cost/attribution.md): Add up the estimated cost of all managed states, attribute spend by a tag such as team, environment, or owner, and follow the cost over time. - [Cloud billing (FOCUS)](https://stategraph.com/docs/infrastructure-as-a-database/cost/billing-sources.md): Connect a FOCUS billing export from AWS, GCP, or Azure to load your actual cloud spend, then read the attributed and unmanaged spend. - [Querying cost data](https://stategraph.com/docs/infrastructure-as-a-database/cost/queries.md): Query Stategraph cost snapshots with SQL to rank resources by cost, break spend down by type or tag, and find coverage gaps across your states. - [Cost in the console](https://stategraph.com/docs/infrastructure-as-a-database/cost/console.md): Use the Costs section of the Stategraph console for a tenant overview, a cost explorer, the analysis of each state, and billing connections. ### Security - [Security scanning](https://stategraph.com/docs/infrastructure-as-a-database/security.md): Scan infrastructure with checkov: findings for each change at plan time, posture over time, and gates on pull requests. ### CI and orchestrators - [CI and orchestrators](https://stategraph.com/docs/infrastructure-as-a-database/ci.md): Use Infrastructure as a Database under GitHub Actions, GitLab CI, Atlantis, or Spacelift, with no global state lock. - [GitHub Actions](https://stategraph.com/docs/infrastructure-as-a-database/ci/github-actions.md): Plan on pull requests and apply on merge with the Stategraph CLI in GitHub Actions, with no app to install. - [GitLab CI](https://stategraph.com/docs/infrastructure-as-a-database/ci/gitlab-ci.md): Plan on merge requests and apply on merge with the Stategraph CLI in GitLab CI, with results on the merge request. - [Atlantis](https://stategraph.com/docs/infrastructure-as-a-database/ci/atlantis.md): Keep Atlantis for pull request automation, and run plans and applies through Stategraph with two run steps. - [Spacelift](https://stategraph.com/docs/infrastructure-as-a-database/ci/spacelift.md): Run Stategraph in Spacelift stacks with the custom workflow tool, and keep Spacelift triggers and approvals. ### AI agents - [AI Agents](https://stategraph.com/docs/infrastructure-as-a-database/ai-agents.md): Use AI agents with Stategraph: six SKILL.md files cover query, change, import, refactor, cost, and routing. ## Administration ### Self-hosting - [Self-hosting](https://stategraph.com/docs/admin/self-hosting.md): Run Stategraph on your own infrastructure: the Open Source and Enterprise editions, their images and deployment paths, and the Enterprise setup. - [Docker Compose](https://stategraph.com/docs/admin/self-hosting/docker-compose.md): Deploy Stategraph with Docker Compose and PostgreSQL, then set up the first account, sign-in, and optional features. - [Kubernetes](https://stategraph.com/docs/admin/self-hosting/kubernetes.md): Deploy Stategraph on Kubernetes with the Helm chart, and set up the ingress, an external PostgreSQL, the health probes, and replicas. - [Amazon ECS](https://stategraph.com/docs/admin/self-hosting/ecs.md): Deploy Stategraph on Amazon ECS Fargate with the Terraform module, an Application Load Balancer, and RDS PostgreSQL. - [Google Cloud Run](https://stategraph.com/docs/admin/self-hosting/cloud-run.md): Deploy Stategraph on Google Cloud Run with Cloud SQL for PostgreSQL, the Cloud SQL Auth Proxy sidecar, and Secret Manager. - [Enable Orchestration](https://stategraph.com/docs/admin/self-hosting/orchestration.md): Set up Stategraph Orchestration on a self-hosted server with database passwords, your public URL, and a GitHub App or GitLab credentials. - [Enable cost estimation](https://stategraph.com/docs/admin/self-hosting/cost.md): Turn on cost estimation in self-hosted Stategraph, give the price book a database, verify it, and mirror it for air gaps. - [Enable security scanning](https://stategraph.com/docs/admin/self-hosting/security-scanning.md): Turn on checkov security scanning on a self-hosted Stategraph server with STATEGRAPH_SECURITY, and set how often each state is scanned. #### Open Source - [Open Source](https://stategraph.com/docs/admin/self-hosting/open-source.md): Self-host the open-source edition of Stategraph Orchestration with Docker Compose, Kubernetes, or Amazon ECS, and find its variables and metrics. - [Kubernetes](https://stategraph.com/docs/admin/self-hosting/open-source/kubernetes.md): Deploy the Open Source edition of Stategraph Orchestration on Kubernetes with the Helm chart, create its secrets, and connect GitHub or GitLab. - [Amazon ECS](https://stategraph.com/docs/admin/self-hosting/open-source/ecs.md): Deploy the Open Source edition of Stategraph Orchestration on AWS with the Terraform module: ECS Fargate, an Application Load Balancer, and RDS. - [Environment variables](https://stategraph.com/docs/admin/self-hosting/open-source/environment-variables.md): Every environment variable that the open-source Stategraph Orchestration container reads: database, GitHub, GitLab, URLs, proxy, and CA certificates. - [Observability and metrics](https://stategraph.com/docs/admin/self-hosting/open-source/observability.md): Prometheus metrics reference for the open-source Stategraph Orchestration server, with sample queries, recommended alerts, and dashboard panels. ### Operations - [Environment variables](https://stategraph.com/docs/admin/operations/environment-variables.md): Look up every environment variable that self-hosted Stategraph reads, with its default value and what it does. - [Upgrades](https://stategraph.com/docs/admin/operations/upgrades.md): Upgrade self-hosted Stategraph safely, with start-time migrations, rolling replacement, release changes, and cosign checks. - [Health checks](https://stategraph.com/docs/admin/operations/health-checks.md): Use the liveness and readiness endpoints of self-hosted Stategraph, with probe settings for Compose, Kubernetes, ECS, and Cloud Run. - [Observability](https://stategraph.com/docs/admin/operations/observability.md): Monitor self-hosted Stategraph through its health endpoints, its container log, its access log, and platform metrics. ### Access control - [Authentication](https://stategraph.com/docs/admin/access-control.md): Set up sign-in to Stategraph with local accounts, Google OAuth, or OIDC, and API keys for the CLI, scripts, and CI pipelines. - [Local Authentication](https://stategraph.com/docs/admin/access-control/local-authentication.md): Set up email and password sign-in for self-hosted Stategraph, and manage users, passwords, and service accounts. - [Google OAuth Setup](https://stategraph.com/docs/admin/access-control/google-oauth.md): Set up Google Workspace sign-in for Stategraph with Google OAuth, and restrict access by email domain or Google Group. - [OIDC Configuration](https://stategraph.com/docs/admin/access-control/oidc.md): Set up Stategraph sign-in through any OIDC provider, such as Okta, Auth0, Azure AD, Keycloak, AWS Cognito, or GitLab. - [Tenants and Administration](https://stategraph.com/docs/admin/access-control/tenants.md): Learn how tenants, members, invitations, and instance and tenant admins work in a self-hosted Stategraph install. - [Access Tokens and Capabilities](https://stategraph.com/docs/admin/access-control/access-tokens.md): Create Stategraph access tokens from the CLI, and limit each token to the admin, plan, apply, and user rights that it needs. - [Group Rules](https://stategraph.com/docs/admin/access-control/group-rules.md): Grant Stategraph plan, apply, and admin rights from identity provider groups at sign-in, with tenant-scoped group rules. ## CLI ### Get started - [CLI](https://stategraph.com/docs/cli.md): Install and configure the stategraph CLI to manage states, run SQL queries and gap analysis, and automate from the terminal. - [Config Commands](https://stategraph.com/docs/cli/config.md): Use the stategraph config commands to edit stategraph.json, attach external files to resource addresses per workspace, and mark tfvars as ephemeral. - [Utility Commands](https://stategraph.com/docs/cli/utilities.md): Use stategraph info to see your user, your tenants, and the versions, and use stategraph version to print the client and server versions. - [Diagnostics](https://stategraph.com/docs/cli/diagnostics.md): Run stategraph diagnostics to trace how Stategraph evaluates your Terraform HCL on your machine, then send the trace to the Stategraph team. ### Commands - [Terraform Commands](https://stategraph.com/docs/cli/tf.md): Reference for stategraph tf plan, apply, show, and mtx, which plan and apply Terraform changes through Stategraph with plan files and cost previews. - [Import Commands](https://stategraph.com/docs/cli/import.md): Use stategraph import tf to create a state and import a Terraform state file and its HCL in one step, or to import only the HCL. - [States Commands](https://stategraph.com/docs/cli/states.md): CLI commands for Terraform states in Stategraph: create, import, export, list, inspect, query, and delete states. - [Transactions Commands](https://stategraph.com/docs/cli/transactions.md): Use the stategraph tx commands to create, list, and abort Stategraph transactions, and to see their cost previews and their logs. - [SQL Commands](https://stategraph.com/docs/cli/sql.md): Query your Terraform resources with SQL from the terminal, page through large results, and read the schema. - [Refactor](https://stategraph.com/docs/cli/refactor.md): Track HCL refactors, such as resource renames and module moves, across plan steps and write Terraform moved blocks. - [HCL Commands](https://stategraph.com/docs/cli/hcl.md): Use the stategraph hcl commands to list Terraform addresses, evaluate expressions, convert HCL and JSON, and import HCL into a state. - [Cost Commands](https://stategraph.com/docs/cli/cost.md): Use the stategraph cost commands to manage FOCUS billing sources and to query state, tenant, attribution, history, and coverage cost data. - [Security Commands](https://stategraph.com/docs/cli/security.md): CLI commands for Stategraph security scanning: findings and scan history of a state, tenant posture, and change impact. - [Tenant Commands](https://stategraph.com/docs/cli/tenant.md): CLI commands for tenant gap analysis: find cloud resources that Terraform does not manage, check the setup, and generate import blocks. - [User Commands](https://stategraph.com/docs/cli/user.md): Use the stategraph user commands to see who you are, list your tenants, and create, list, and delete your Stategraph access tokens. - [Capabilities Commands](https://stategraph.com/docs/cli/capabilities.md): Use the stategraph capabilities commands to set the default capabilities of new users and to grant capabilities by identity provider group. ## Reference ### General - [Reference](https://stategraph.com/docs/reference.md): Find the exact syntax for Stategraph: the configuration file, pull request commands, the CLI, the API, and the SQL language. - [Troubleshooting](https://stategraph.com/docs/reference/troubleshooting.md): Fix common Stategraph errors with sign-in, the stategraph CLI, the console, gap analysis, cost, and Orchestration on GitHub and GitLab. - [Releases & Downloads](https://stategraph.com/docs/reference/releases.md): Install the Stategraph CLI, pull the Stategraph container, verify image signatures, and find the release notes for each version. - [Terraform CLI Compatibility](https://stategraph.com/docs/reference/terraform-compatibility.md): See how each Terraform CLI command and HCL construct maps to Stategraph: direct equivalents, transaction replacements, and gaps. ### API - [Stategraph API](https://stategraph.com/docs/reference/api.md): The Stategraph REST API: base URL, API keys, sessions, and access tokens, the OpenAPI schema, pagination, errors, and rate limits. - [Users and sign-in](https://stategraph.com/docs/reference/api/users.md): API endpoints for the current user, their tenants, and their GitHub and GitLab users, and for login options, login, logout, and first-time setup. - [User management](https://stategraph.com/docs/reference/api/user-management.md): API endpoints that list, create, update, and delete users, change passwords, set the installation admin, and create service accounts. - [Tenants and members](https://stategraph.com/docs/reference/api/tenants.md): API endpoints that create and rename tenants, manage members and their roles, and create, reissue, revoke, preview, and accept invitations. - [API keys and access tokens](https://stategraph.com/docs/reference/api/access-tokens.md): API endpoints for API keys, default capabilities, and capability group rules, and for refresh tokens and the short-lived access tokens they issue. - [States](https://stategraph.com/docs/reference/api/states.md): API endpoints that create, import, export, and delete states, serve the Terraform HTTP backend, and read instances, modules, and summaries. - [Transactions and tasks](https://stategraph.com/docs/reference/api/transactions.md): API endpoints that list, create, read, and abort transactions, read their logs, plan operations, and output, and poll long-running tasks. - [Queries and gap analysis](https://stategraph.com/docs/reference/api/queries.md): API endpoints that run SQL queries across all states, return the SQL schema, and find and import the cloud resources that no state manages. - [Cost and billing](https://stategraph.com/docs/reference/api/cost.md): API endpoints for estimated and actual cost per state and tenant, cost history and attribution, plan-time cost, and cloud billing sources. - [Security](https://stategraph.com/docs/reference/api/security.md): API endpoints for security scans: the findings of a state, their summary, scan history, tenant posture over time, and transaction impact. - [VCS installations](https://stategraph.com/docs/reference/api/vcs-installations.md): API endpoints for GitHub and GitLab installations: tenant links, repositories, pull requests, dirspaces, work manifests, groups, and webhooks. - [Stacks](https://stategraph.com/docs/reference/api/stacks.md): API endpoint that returns the stacks of a pull request: their definitions, dependencies, dirspaces, execution order, and plan and apply status. - [Key-value store](https://stategraph.com/docs/reference/api/kv-store.md): API endpoints for the key-value store of an installation: set, get, delete, compare-and-swap, iterate, count, measure, and commit keys. - [Server](https://stategraph.com/docs/reference/api/server.md): API endpoints that return the version of the server, its feature flags, its GitHub and GitLab configuration, and the GitHub App client ID. ### Infrastructure as a Database - [SQL Syntax Reference](https://stategraph.com/docs/reference/sql-syntax.md): Read the grammar of Stategraph SQL, the subset of SQL that queries your infrastructure: clauses, operators, functions, and row limits. ### Orchestration #### Configuration keys - [access_control](https://stategraph.com/docs/reference/orchestration/configuration/access-control.md): Reference for the access_control key in .stategraph/config.yml. Define who can plan, apply, unlock, and override apply requirements. - [Apply Requirements and Overrides](https://stategraph.com/docs/reference/orchestration/configuration/apply-requirements.md): Reference for the apply_requirements key in .stategraph/config.yml. Configure approvals, merge conflict and status checks, and overrides. - [automerge](https://stategraph.com/docs/reference/orchestration/configuration/automerge.md): Reference for the automerge key in .stategraph/config.yml. Merge the pull request automatically after every directory applies successfully. - [batch_runs](https://stategraph.com/docs/reference/orchestration/configuration/batch-runs.md): Reference for the batch_runs key in .stategraph/config.yml. Limit how many workspaces a single CI run executes in large repositories. - [config_builder](https://stategraph.com/docs/reference/orchestration/configuration/config-builder.md): Reference for the config_builder key in .stategraph/config.yml. Generate the repository configuration at runtime with a custom script. - [cost_estimation](https://stategraph.com/docs/reference/orchestration/configuration/cost-estimation.md): Reference for the cost_estimation key in .stategraph/config.yml. Post Infracost monthly cost changes alongside every plan comment. - [default_branch_overrides](https://stategraph.com/docs/reference/orchestration/configuration/default-branch-overrides.md): Reference for the default_branch_overrides key in .stategraph/config.yml. Choose which root keys are read from the default branch. - [definitions](https://stategraph.com/docs/reference/orchestration/configuration/definitions.md): Reference for the definitions key in .stategraph/config.yml. Hold YAML anchors that other sections reuse, with the merge rules that apply. - [destination_branches](https://stategraph.com/docs/reference/orchestration/configuration/destination-branches.md): Reference for the destination_branches key in .stategraph/config.yml. Control which target and source branches trigger operations. - [dirs](https://stategraph.com/docs/reference/orchestration/configuration/dirs.md): Reference for the dirs key in .stategraph/config.yml. Assign tags, workspaces, and when_modified rules to directories, with glob matching. - [drift](https://stategraph.com/docs/reference/orchestration/configuration/drift.md): Reference for the drift key in .stategraph/config.yml. Schedule drift detection and reconciliation, set run windows, and create issues. - [enabled](https://stategraph.com/docs/reference/orchestration/configuration/enabled.md): Reference for the top-level enabled key in .stategraph/config.yml. Turn Stategraph Orchestration on or off for a whole repository. - [engine](https://stategraph.com/docs/reference/orchestration/configuration/engine.md): Reference for the engine key in .stategraph/config.yml. Choose Terraform, OpenTofu, Terragrunt, CDKTF, Pulumi, Stategraph, or a custom engine. - [hooks](https://stategraph.com/docs/reference/orchestration/configuration/hooks.md): Reference for the hooks key in .stategraph/config.yml. Run commands, set environment variables, and open OIDC sessions before and after runs. - [indexer](https://stategraph.com/docs/reference/orchestration/configuration/indexer.md): Reference for the indexer key in .stategraph/config.yml. Generate directory and module configuration by analyzing your Terraform code. - [lock_policy](https://stategraph.com/docs/reference/orchestration/configuration/lock-policy.md): Reference for the lock_policy key in .stategraph/config.yml. Decide when a directory and workspace acquire a lock across the repository. - [notifications](https://stategraph.com/docs/reference/orchestration/configuration/notifications.md): Reference for the notifications key in .stategraph/config.yml. Control comment strategies, the run summary, and per-dirspace status checks. - [parallel_runs](https://stategraph.com/docs/reference/orchestration/configuration/parallel-runs.md): Reference for the parallel_runs key in .stategraph/config.yml. Set how many Terraform runs execute concurrently across directories. - [stacks](https://stategraph.com/docs/reference/orchestration/configuration/stacks.md): Reference for the stacks key in .stategraph/config.yml. Group dirspaces into named stacks with shared variables and ordering rules. - [storage](https://stategraph.com/docs/reference/orchestration/configuration/storage.md): Reference for the storage key in .stategraph/config.yml. Keep plan files in the server database, an S3 bucket, custom commands, or nowhere. - [tags](https://stategraph.com/docs/reference/orchestration/configuration/tags.md): Reference for the top-level tags key in .stategraph/config.yml. Derive dest_branch and branch tags from branch names with Lua patterns. - [tree_builder](https://stategraph.com/docs/reference/orchestration/configuration/tree-builder.md): Reference for the tree_builder key in .stategraph/config.yml. Replace Git change detection with a script that lists files and their content IDs. - [version](https://stategraph.com/docs/reference/orchestration/configuration/version.md): Reference for the version key in .stategraph/config.yml. The configuration file format version, which must be the quoted string "1". - [when_modified](https://stategraph.com/docs/reference/orchestration/configuration/when-modified.md): The when_modified key in .stategraph/config.yml sets file patterns, autoplan, autoapply, prechecks, and the depends_on order of directories. - [work_manifests](https://stategraph.com/docs/reference/orchestration/configuration/work-manifests.md): Reference for work_manifests in .stategraph/config.yml. Set how long a run has to call home and how long it may run before Orchestration aborts it. - [workflows](https://stategraph.com/docs/reference/orchestration/configuration/workflows.md): The workflows key in .stategraph/config.yml sets the plan and apply steps, engine, environment, OIDC, gates, and scanners per directory. - [Tag Queries](https://stategraph.com/docs/reference/orchestration/configuration/tag-queries.md): Reference for tag queries in .stategraph/config.yml. Define tags, combine them with and, or, not, and in, and target workflows and commands. - [Ignoring a Directory](https://stategraph.com/docs/reference/orchestration/configuration/ignore-patterns.md): Configure .stategraph/config.yml so that changes in specific directories or files never trigger automatic plans and applies. #### Pull request commands - [stategraph help](https://stategraph.com/docs/reference/orchestration/commands/help.md): Stategraph Orchestration takes its commands from pull request comments, and stategraph help lists each command with its basic usage. - [stategraph plan](https://stategraph.com/docs/reference/orchestration/commands/plan.md): Run the plan workflow from a pull request comment, for every changed directory, or only for the directories that match a tag query. - [stategraph apply](https://stategraph.com/docs/reference/orchestration/commands/apply.md): Apply the stored plans of a pull request from a comment, for every planned directory, or only for the directories that match a tag query. - [stategraph apply-autoapprove](https://stategraph.com/docs/reference/orchestration/commands/apply-autoapprove.md): A reserved pull request comment to plan and apply in one step with no review between them, which Orchestration does not run. - [stategraph apply-force](https://stategraph.com/docs/reference/orchestration/commands/apply-force.md): Run an apply from a pull request comment even when the apply requirements are not met, without Gatekeeper gates, as a trusted user. - [stategraph unlock](https://stategraph.com/docs/reference/orchestration/commands/unlock.md): Release the locks of a pull request or of drift detection from a pull request comment, so that other pull requests and drift runs can proceed. - [stategraph gate approve](https://stategraph.com/docs/reference/orchestration/commands/gate-approve.md): Approve failed Gatekeeper gates by their tokens from a pull request comment, so that the apply can proceed. - [stategraph repo-config](https://stategraph.com/docs/reference/orchestration/commands/repo-config.md): Print the fully evaluated repository configuration from a pull request comment, with config builder, indexer, and override outputs. - [stategraph feedback](https://stategraph.com/docs/reference/orchestration/commands/feedback.md): Record feedback, an issue report, or a suggestion from a pull request comment, and find the other support channels. ## Support - [Support](https://stategraph.com/docs/support.md): Contact Stategraph support, and send the pull request, patch, configuration, and logs that support needs to reproduce a problem.