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
- A team's
writ serve, as in Run a control plane, with an issuer of kindgitlab-ci. - Your project, added as a repository.
Know the three jobs
You get three templates from the component in ci/gitlab, in ci/gitlab/templates, each with GIT_STRATEGY: none:
| Template | Job | Runs | Does |
|---|---|---|---|
writ-plan.yml | writ-plan-STACK-ENV | In each merge request pipeline | writ plan --remote --commit "$CI_COMMIT_SHA" |
writ-approve.yml | writ-approve | In each merge request pipeline, manual, blocking | writ approve --remote --pipeline |
writ-apply.yml | writ-apply-STACK-ENV | On a push to the default branch | writ 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.
Print the CI lines and the config
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:
- Add the lines to
.gitlab-ci.yml. - Add the blocks to your
writ serveconfig. - 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.comFrom 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
- Approve and apply a plan: what the approve and apply jobs do, and how to recover when an answer is lost.
- Sign in: sign-in for people.
This page is built from docs/set-up-gitlab-ci.md in the repository. It is also served as plain Markdown.