Overview
What Writ is, and where to find each page of the docs.
Writ is an open-source control plane for OpenTofu that you host yourself. You point writ serve at a Git repository of stacks. It plans the commits you or your CI job send it, waits for the approvals your rules require, and applies the plan it kept. Your CI jobs and laptops never hold a cloud credential or a state key.
Writ is at version 0. Status and limits lists what's built, how it's tested, and what's missing. Read it before you rely on Writ.
Start here
New to Writ? Follow the quick start. You'll plan and apply a stack on your own machine, with no cloud account, then set Writ up for a team.
| If you want to | Read |
|---|---|
| Try Writ on your machine | Quick start |
Get the writ binary or the container image | Install |
| Run it for your team | Run a control plane, then the server config |
| Plan and apply from CI | Set up GitLab CI |
| Know what it can't do yet | Status and limits |
| Compare it with what you use today | Other control planes, or OpenTofu in plain GitLab CI |
Concepts
How Writ works, and why it's built that way.
- How the control plane works: how
writ serveplans a commit, runs OpenTofu apart from its keys, keeps state, checks drift, and decides who can do what. - Repositories: how the control plane reads your code by commit.
- Approvals: approval rules, who can approve, stale plans, and what each run records.
- Secrets and the mask: how secrets stay out of everything
writ servestores or shows, and the cases the mask can't catch. - Policy: Rego policies that check each plan when it's created and again before its apply.
Guides
One task each, step by step.
- Run a control plane:
writ serve --devfor you, and a team'swrit serve. - Sign in:
writ loginand the control UI. - Add a repository: a local repository or a GitLab project.
- Set up GitLab CI: the plan, approve, and apply jobs.
- Approve and apply a plan: by id, after a merge, and with an override.
- Adopt a state: bring in a state Writ didn't write.
- Write and test a policy: Rego,
conftest, and the examples. - Import many objects: write code for objects you already run, in one pass.
- Use Writ with an agent: the skill
writ agent initinstalls, andwrit mcp.
Reference
Exact values, flags, routes, and messages.
- Commands: every command, flag, and exit code.
- Server config: every setting of the
writ serveconfig. - API: every route, token checks, and limits.
- Errors: each error class, its exit code and status, and what to do.
- JSON output: the contract for every
--jsondocument. - Control database: what
writ servekeeps. - Policy input and built-ins: what a policy reads and can call.
- Reference for agents: the tools of
writ mcp, and how to recover from each refusal. - Glossary: the terms these pages use.
Contribute
- Development: how to build and test Writ.
- Architecture: the package map, and the decisions behind it.
- Writing style: the voice and terms these pages follow.
This page is built from docs/README.md in the repository. It is also served as plain Markdown.