Quick start
Try Writ on your own with writ serve --dev and no cloud account, then set it up for a team, where a second person approves the plan.
Plan and apply a real OpenTofu stack with Writ on your own machine. You don't need a cloud account, and it takes four steps. When you're ready, set it up for a team: a merge request job plans a stack, its author can't approve the plan, and a second person does.
Try Writ on your own
writ serve --dev runs a control plane for you alone, on loopback, with its records in SQLite. It's the same code as a team's writ serve, without sign-in or approval rules. The stack below uses hashicorp/random, which doesn't reach any cloud.
Before you begin
- Linux, and
minisign, which the install script needs to check the release's signature. - Git, with your commit name and email set.
- OpenTofu 1.13.9 on your
PATH, and network access toregistry.opentofu.org.
1. Install writ
The install script puts writ v0.1.0 in ~/.local/bin, after it checks the release's signature and checksum:
curl -fsSL https://github.com/mr-karan/writ/releases/download/v0.1.0/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
writ versionTo build from source instead, you need Go 1.27.3 or later and just. Run git clone https://github.com/mr-karan/writ, then just build in it, and put its bin on your PATH. With Nix, nix develop in the repository gives you Go, just, and OpenTofu 1.13.9. Install has the other ways to get writ.
2. Start the dev control plane
Run this in one terminal, and leave it running:
$ writ serve --dev
writ serve --dev: http://127.0.0.1:7340, for alice only
data: /home/alice/.local/share/writ/dev (control.db, state/, keys/)
OpenTofu runs get PATH=/usr/local/bin:/usr/bin:/bin and this shell's TF_VAR_ variables, and no other variable of this shell.
control UI: http://127.0.0.1:7340/ui/login/dev?code=KLBC-ZBYU (works once, for 10 minutes; writ ui prints another)
ready in 102 msOutput of a real run, 2026-11-16.
Open the control UI link to sign your browser in to the control UI, where you can see each plan and run.
Your OpenTofu runs get no other variable from that shell, and each run's HOME is its own directory. So a provider won't find a cloud credential in your shell's environment or your home directory.
3. Create a stack and add its repository
Open a second terminal, and check that writ is on its PATH there too. Then create a Git repository with one stack: a directory of .tf files with a committed .terraform.lock.hcl. With backend "http" {}, writ serve keeps its state for you.
mkdir -p ~/writ-demo/app
cd ~/writ-demo
git init -b main
cat > app/main.tf <<'EOF'
terraform {
backend "http" {}
required_providers {
random = { source = "hashicorp/random", version = "3.9.1" }
}
}
resource "random_pet" "name" {
length = 2
}
output "name" {
value = random_pet.name.id
}
EOF
(cd app && tofu providers lock)
git add .
git commit -m "one stack"Then add the repository to the control plane:
$ writ repo add .
Repository writ-demo: /home/alice/writ-demo, path the root, branch main.
Read main at 570edf03 from the local repository: 1 file, 1 stack.
STACK SERVED
app dev
Next: in a clean work tree of it, writ plan --remote plans the commit you are on.4. Plan and apply
Plan the commit, then apply the plan by its id. Your first plan downloads the provider, so it takes longer. The last command plans again, to show that nothing is left to change:
$ cd app
$ writ plan --remote
commit plan of app@dev: repository writ-demo at 570edf03 (main), sent to http://127.0.0.1:7340
OpenTofu 1.13.9 plan of app@dev
+ random_pet.name (create)
Plan: 1 to add, 0 to change, 0 to destroy.
Outputs that change: name.
Plan 7ff2ad97b106fcbf4b4633baee25626a for dev (app), by alice (dev), expires 2026-11-17T05:32:18Z.
It is a commit plan of writ-demo at 570edf03.
It needs no approval. Apply it with: writ apply --remote 7ff2ad97b106fcbf4b4633baee25626a
$ writ apply --remote 7ff2ad97b106fcbf4b4633baee25626a
Run I3EP3I6DTYNC5PMVULSW6JYINL of plan 7ff2ad97b106fcbf4b4633baee25626a for dev (app), by alice (dev).
OpenTofu apply of app@dev
random_pet.name: create complete
Apply: 1 added, 0 changed, 0 destroyed.
State version 1 of app@dev.
Run I3EP3I6DTYNC5PMVULSW6JYINL of plan 7ff2ad97b106fcbf4b4633baee25626a for dev (app), by alice (dev): applied at 2026-11-16T05:32:19Z.
$ writ plan --remote
commit plan of app@dev: repository writ-demo at 570edf03 (main), sent to http://127.0.0.1:7340
OpenTofu 1.13.9 plan of app@dev
No changes.
Plan 096e5fe23db797b5b8b81eb9722c2199 for dev (app), by alice (dev), expires 2026-11-17T05:32:20Z.
It is a commit plan of writ-demo at 570edf03.
It has no change to apply.Output of a real run, 2026-11-16.
To list the runs, newest first, use writ runs --remote:
$ writ runs --remote --stack app
RUN STARTED STACK STATUS BY PLAN
I3EP3I6DTYNC5PMVULSW6JYINL 2026-11-16T05:32:18Z app applied alice (dev) 7ff2ad97b106fcbf4b4633baee25626aThe dev control plane has no approval rule, so your plans don't need approvals. When you're done, stop it with Ctrl-C.
Set up Writ for a team
On a team, each merge request should show the plan it would apply, and someone other than its author should approve that plan. A team's writ serve adds what the dev control plane leaves out: Postgres, OIDC sign-in for CI jobs and people, teams and grants, approval rules, and its own uid for each run.
Here you set up one GitLab project, acme/infra, with one stack, app, in one environment, prod. CI jobs plan, approve, and apply. People sign in with writ login from a terminal, or to the control UI in a browser, to read the plans and runs.
Limits.
- No pipeline on a real GitLab has run these steps. The output below comes from
TestTofuApproveApplyine2e/tofu_apply_test.go, which runs them against a team'swrit servewith Postgres, a test issuer, and a stand-in of GitLab. - No run of
writ loginhas used a real GitLab. GitLab.com offers no device flow, sowrit loginsigns you in through a browser, with a redirect to a loopback port that changes on each sign-in. That GitLab accepts it on any port is inferred from the Doorkeeper version it pins, as Set up writ login explains. If it doesn't, sign in to the control UI instead.
Before you begin
- A Linux host with Postgres,
writ, and OpenTofu 1.13.9, behind a proxy that ends TLS forhttps://writ.example.com. - The GitLab project
acme/infraand its numeric id, here4242. A renamed project keeps its id. - A
writimage in a registry your runners can pull from, hereregistry.example.com/writ:0.1.0, a copy ofghcr.io/mr-karan/writ:0.1.0.
1. Commit the stack to the default branch
Commit app to main before you add any CI jobs: its .tf files and its .terraform.lock.hcl. writ serve finds stacks on the default branch, so it serves app from its first read of the project. writ ci gitlab also refuses a repository whose default branch has no stack it serves.
2. Write the config
On the host, write one HCL file. It sets the GitLab issuer of CI tokens, the people issuer you sign in with, the Git host and its read-only token, the repository, four teams, a grant for each, one approval rule, the environment's state key, and how to run OpenTofu:
url = "https://writ.example.com"
listen = "127.0.0.1:8443"
trusted_proxies = ["127.0.0.1/32"]
database = "postgres://writ@/writ?host=/run/postgresql"
provider_uids = "61000-61063"
issuer "gitlab" {
kind = "gitlab-ci"
identity = "gitlab"
url = "https://gitlab.com"
}
issuer "sso" {
kind = "people"
identity = "gitlab"
url = "https://gitlab.com"
client_id = "8f1c0b7e4d2a"
client_secret_file = "secrets/oidc_client_secret"
groups = "userinfo"
}
forge "gitlab" {
kind = "gitlab"
url = "https://gitlab.com"
read_token_file = "secrets/gitlab_read"
}
repo {
name = "infra"
forge = "gitlab"
project = "acme/infra"
}
team "infra_mr" {
issuer = "gitlab"
match = { project_id = ["4242"], pipeline_source = ["merge_request_event"] }
}
team "infra_reviewers" {
issuer = "gitlab"
match = { project_id = ["4242"], user_access_level = ["maintainer", "owner"] }
}
team "infra_main" {
issuer = "gitlab"
match = { project_id = ["4242"], ref_path = ["refs/heads/main"], ref_protected = ["true"] }
}
team "acme" {
issuer = "sso"
match = { groups = ["acme"] }
}
grant {
teams = ["infra_mr"]
stacks = ["app"]
envs = ["prod"]
can = ["read", "plan"]
}
grant {
teams = ["infra_reviewers"]
stacks = ["app"]
envs = ["prod"]
can = ["approve"]
}
grant {
teams = ["infra_main"]
stacks = ["app"]
envs = ["prod"]
can = ["read", "apply"]
risks = ["create", "update", "replace", "delete"]
}
grant {
teams = ["acme"]
stacks = ["app"]
envs = ["prod"]
can = ["read"]
}
approval {
stacks = ["app"]
envs = ["prod"]
risks = ["create", "update", "replace", "delete", "data-loss"]
need = 1
}
env "prod" {
key = "keys/prod.key"
}
tofu {
binary = "tofu"
plugin_cache = "/var/lib/writ-tofu/plugins"
scratch_dir = "/var/lib/writ-tofu/runs"
}secrets/gitlab_readhas a GitLab token withread_api. Repositories says which token to create.secrets/oidc_client_secrethas the secret of a GitLab application whose id isclient_id, with the scopesopenid profile emailand two redirect URIs, one per line:https://writ.example.com/ui/callbackfor the control UI, andhttp://127.0.0.1/callbackforwrit login. Sign in explains both flows.- The team
acmeis every person in the GitLab groupacme. Its grant to readappinprodlets them see plans and runs, from a terminal or in the control UI. - Approvals come from
infra_reviewers, the project's maintainers and owners, through the pipeline's approve job. To let people approve from a plan's page in the control UI too, addapproveto theacmegrant. Both issuers have the identitygitlab, so a person and the CI jobs they start count as one person, and the author still can't approve. keys/prod.keyhas the 32 random bytes that seal the environment's state and saved plans:head -c 32 /dev/urandom > keys/prod.key, mode 0600. Back it up offline.listenis a loopback address, so your proxy ends TLS forurl.- A stack on S3 also needs AWS plan and apply roles. See Roles and credentials, and the server config for every other setting.
3. Check the config, then start writ serve
Run writ serve --config serve --check first. It reads the config, prints what each team can do, and runs tofu version. It doesn't contact Postgres, GitLab, or the issuers.
When it can switch users, it also runs writ as the first provider uid. That uid tries to read the state keys, the TLS key, the provider_env files, and the data directory, and to connect to the EC2 instance metadata addresses, 169.254.169.254 and fd00:ec2::254, on port 80. For an address the uid couldn't reach, writ then tries the address itself, to tell an address the host blocks from one where no metadata service answers. If the uid can read a secret or reach an address, the check fails. This run was as a user who can't switch users, so the isolation check only warns:
$ writ serve --config serve --check
config serve: ok
url: https://writ.example.com
issuers: gitlab (gitlab-ci, https://gitlab.com), sso (people, https://gitlab.com, client 8f1c0b7e4d2a)
control UI: https://writ.example.com/ui/, sign-in redirects to https://writ.example.com/ui/callback, sessions last 12h0m0s
envs: prod, state in postgres://writ@/writ
trusted proxies: 127.0.0.1/32; X-Forwarded-For names the client only when one of them sends it
providers run as: uids 61000-61063, one for each running plan
tofu: tofu, plugin cache /var/lib/writ-tofu/plugins, scratch directories in /var/lib/writ-tofu/runs
approvals: rule 1: app in prod with create update replace delete data-loss needs 1
TEAM ENV STACKS CAN RISKS
acme prod app read -
infra_main prod app read apply create update replace delete
infra_mr prod app read plan -
infra_reviewers prod app approve -
tofu: /nix/store/60vqi4v8n11afd5ks89j1kn7pgwfrww5-opentofu-1.13.9/bin/tofu is OpenTofu 1.13.9: ok
warning[usage]
isolation not checked: run writ as provider uid 61000: fork/exec /var/tmp/writ-landing2/qs/bin/writ: operation not permitted; writ serve checks its capabilities at startOutput of a real run, 2026-11-16.
Then start it with writ serve --config serve. On NixOS, the module runs it with Postgres, the capabilities that provider_uids needs, and --check before each start.
4. Sign in from your terminal
On your laptop, run writ login https://writ.example.com. GitLab.com offers no device flow, so writ login prints a GitLab URL, and opens it in your browser when it can. Sign in at GitLab, and GitLab sends your browser back to writ login:
$ writ login http://127.0.0.1:35309
Signing in to http://127.0.0.1:35309 through issuer sso.
To sign in, open https://127.0.0.1:36093/oauth/authorize?client_id=writ-e2e&code_challenge=QqueYeHu6tMmOgOABEnQeLVDZ4E2tW41WqKkByO5AdM&code_challenge_method=S256&nonce=BV_F4WYQLxLGVMYFi9phIfQaGZKgk6l7-QCRw0TZzEU&redirect_uri=http%3A%2F%2F127.0.0.1%3A36443%2Fcallback&response_type=code&scope=openid+profile+email&state=BGX7AJ5XD2T6KK7AUC6OMKYHR2 in a browser on this computer.
The sign-in expires in 10 minutes.
Signed in to http://127.0.0.1:35309 as bob (gitlab/user/2002).
Teams: acme
Session ends 2026-11-16T20:39:54Z.
$ writ whoami
http://127.0.0.1:35309 (from your session), session of bob (gitlab/user/2002, issuer sso), ends 2026-11-16T20:39:54Z
teams: acme
prod app read -Output of TestTofuApproveApply, 2026-11-16, where writ serve listens on a loopback address, a test issuer stands in for GitLab, and a script follows the URL as your browser would.
Your browser must run on the computer where you run writ login, because GitLab sends it to a loopback address there. If GitLab shows an error about the redirect URI instead of sending you back, check that the application lists http://127.0.0.1/callback.
You can also sign in in a browser only. Open https://writ.example.com/ui/repos/infra and sign in with GitLab. The page lists app, served in prod.
5. Add the CI jobs in a merge request
Open a merge request that adds these lines to .gitlab-ci.yml:
stages: [writ-plan, writ-approve, writ-apply]
include:
- component: $CI_SERVER_FQDN/platform/writ-ci/writ-plan@0.1.0
inputs:
server: https://writ.example.com
env: prod
stack: app
image: registry.example.com/writ:0.1.0
- component: $CI_SERVER_FQDN/platform/writ-ci/writ-approve@0.1.0
inputs:
server: https://writ.example.com
image: registry.example.com/writ:0.1.0
- component: $CI_SERVER_FQDN/platform/writ-ci/writ-apply@0.1.0
inputs:
server: https://writ.example.com
env: prod
stack: app
image: registry.example.com/writ:0.1.0The include lines point to the components in ci/gitlab, as a project platform/writ-ci on your GitLab, at version 0.1.0. Put a copy there, or change the paths. None of the three jobs needs a checkout or holds a cloud credential:
- In each merge request pipeline,
writ-plan-app-prodplans the commit. - In each merge request pipeline,
writ-approveis a manual job that blocks the merge until each plan has its approvals. - On the default branch,
writ-apply-app-prodapplies the approved plan whose sources equal the merged commit's.
These are the lines writ ci gitlab --repo infra --image registry.example.com/writ:0.1.0 prints for this config, with the teams, grants, and approval rule you already wrote. Set up GitLab CI shows its whole output. It needs a token that can read a stack, so run it in a CI job, with the job's WRIT_ID_TOKEN, as TestTofuApproveApply does. From a laptop it would need writ login.
Protect main, and turn on "Pipelines must succeed" in the project's settings.
6. Plan, approve, and apply
Nothing has applied app yet, so the plan job in alice's merge request creates every resource. It prints the masked plan, which the people of acme also see in the control UI:
OpenTofu 1.13.9 plan of app@prod
+ random_pet.name (create)
+ terraform_data.note (create)
+ terraform_data.secret (create)
+ module.cert.tls_private_key.key (create)
Plan: 4 to add, 0 to change, 0 to destroy.
Outputs that change: pet.Output of TestTofuApproveApply, 2026-11-16.
If alice tries to approve the plan with a token from that pipeline, Writ refuses, because alice created it:
$ writ approve --remote 927b69ec7af23641c68c3ce3cce370ec
error: denied: gitlab acme/infra #1849401 (alice) made plan 927b69ec7af23641c68c3ce3cce370ec and cannot approve it: it needs 1 approval from someone elseIf the merge request merges anyway, the job on main applies nothing:
$ writ apply --remote --merged --env prod --stack app
error: denied: plan 927b69ec7af23641c68c3ce3cce370ec of app@prod matches the sources at 3008b0c3 and needs 1 approval; approve it with writ approve --remote 927b69ec7af23641c68c3ce3cce370ecbob, a maintainer, runs the approve job of the same pipeline:
$ writ approve --remote 927b69ec7af23641c68c3ce3cce370ec
Approved plan 927b69ec7af23641c68c3ce3cce370ec for prod (app): 1 of 1 approvals (gitlab acme/infra #1849401 (bob)), approved.The job on main then applies the plan bob approved. It's the saved plan writ serve kept, so no file comes from the job:
OpenTofu apply of app@prod
terraform_data.note: create complete
terraform_data.secret: create complete
random_pet.name: create complete
module.cert.tls_private_key.key: create complete
Apply: 4 added, 0 changed, 0 destroyed.
State version 1 of app@prod.Output of TestTofuApproveApply, 2026-11-16.
If alice pushes a new commit to the merge request, the pipeline creates a new plan, and the approved one stops applying. Why an approved plan can still be refused shows that refusal.
Next steps
- Approvals and Approve and apply a plan: approval rules, who can approve, stale plans, and overrides.
- Set up GitLab CI: the three jobs, and how each gets its token.
- Sign in:
writ loginin both its flows, and the control UI. - Policy: Rego policy that checks each plan.
- Writ compared with OpenTofu in plain GitLab CI: what Writ adds to a pipeline that runs
tofuitself, and what it costs.
This page is built from docs/quick-start.md in the repository. It is also served as plain Markdown.