Writ

Set up GitLab CI

Plan, approve, and apply from GitLab CI jobs with no checkout and no cloud credential.

With GitLab CI and Writ, every merge request shows the exact plan it would apply, and nothing reaches production until someone other than the author approves that plan. It takes three jobs:

  • a merge request pipeline plans each stack in each environment,
  • a manual job blocks the merge until each plan has its approvals,
  • and the pipeline on the default branch applies each approved plan.

None of your jobs needs a checkout, and none holds a cloud credential or the state key. Each job proves who it is with the OIDC token GitLab issues. To see what happens to each plan, read How the control plane works. To see who can approve it, read Approvals.

Limits. The components are a sketch: no GitLab pipeline has run them. The test plan checks them, and the component's notes list what a real GitLab must show. Among those: whether a manual job's token identifies the person who ran it, and the values of user_access_level.

Before you begin

Know the three jobs

You get three templates from the component in ci/gitlab, in ci/gitlab/templates, each with GIT_STRATEGY: none:

TemplateJobRunsDoes
writ-plan.ymlwrit-plan-STACK-ENVIn each merge request pipelinewrit plan --remote --commit "$CI_COMMIT_SHA"
writ-approve.ymlwrit-approveIn each merge request pipeline, manual, blockingwrit approve --remote --pipeline
writ-apply.ymlwrit-apply-STACK-ENVOn a push to the default branchwrit apply --remote --merged

For example, ci/gitlab/templates/writ-plan.yml is a CI/CD component that adds a writ-plan-STACK-ENV job to merge request pipelines, and ci/gitlab/example.gitlab-ci.yml includes it. That job runs writ plan --remote --stack STACK --commit "$CI_COMMIT_SHA", and writ serve fetches the commit from the repository whose project id is the token's.

Turn on "Pipelines must succeed". Then the blocking approve job keeps your merge request from merging until someone runs it, and it passes only when each plan of the pipeline has its approvals.

You don't have to write the jobs or the config by hand. Run writ ci gitlab --repo NAME, and it prints the .gitlab-ci.yml lines and the teams, grants, and approval rule your config needs, by the project's id. You get a plan job and an apply job for each stack and environment the control plane serves, and one blocking approve job:

$ writ ci gitlab --repo infra --image registry.example.com/writ:0.1.0
# .gitlab-ci.yml: add these lines. A merge request pipeline plans each stack in each
# environment, and its manual approve job blocks the merge until each plan has its
# approvals. The pipeline on the default branch applies each approved plan whose sources
# equal the merged commit's. No job needs a checkout.
stages: [writ-plan, writ-approve, writ-apply]
include:
  - component: $CI_SERVER_FQDN/platform/writ-ci/writ-plan@0.1.0
    inputs:
      server: http://127.0.0.1:40185
      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: http://127.0.0.1:40185
      image: registry.example.com/writ:0.1.0
  - component: $CI_SERVER_FQDN/platform/writ-ci/writ-apply@0.1.0
    inputs:
      server: http://127.0.0.1:40185
      env: prod
      stack: app
      image: registry.example.com/writ:0.1.0

# The writ serve config: the teams and grants of this repository's pipelines, by the
# project's id, 4242, which a renamed project keeps, and an approval rule.
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"] }
}
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"]
}
approval {
  stacks = ["app"]
  envs   = ["prod"]
  risks  = ["create", "update", "replace", "delete", "data-loss"]
  need   = 1
}

# Project settings of acme/infra: protect main, and turn on "Pipelines must succeed".

Output of TestTofuApproveApply, 2026-11-16, against a team's writ serve on loopback.

Then:

  1. Add the lines to .gitlab-ci.yml.
  2. Add the blocks to your writ serve config.
  3. Set up the project as the last comment says.

How a job gets its token

Your job's token comes from id_tokens:

id_tokens:
  WRIT_ID_TOKEN:
    aud: https://writ.example.com

From there, the client reads WRIT_SERVER and WRIT_ID_TOKEN. It sends a token only over HTTPS, or over HTTP to a loopback address.

To see what a job did, use writ plan --remote --json, which prints the writ.remote-plan/v0 document. You can also run writ show --remote ID and writ runs --remote to print what the control plane keeps.

Next steps

This page is built from docs/set-up-gitlab-ci.md in the repository. It is also served as plain Markdown.

On this page