Keep your GitLab groups and projects in a declared state, with guardrails and drift correction.
Full documentation lives at intentius.io/gitlab-warden, with deep dives on these pages.
From a checkout, Claude Code picks up the skill in
.claude/skills/gitlab-warden automatically. Other agents can install it with
npx skills add INTENTIUS/gitlab-warden, or by copying the skill directory
into ~/.claude/skills/. Then paste this prompt, filling in the placeholders:
Use the gitlab-warden skill to help me set up governance for my GitLab group
<GROUP_PATH> on <GITLAB_URL>. Author a governance.yml nodes: policy for the
groups and projects I care about (ask me which slices matter), then run a
dry-run reconcile and walk me through the plan. Do not apply anything.
The skill holds the agent to dry-run until you've reviewed the plan; deletes
stay off entirely until you mark a node owned in the policy.
- A clone of this repo (
git clone https://github.com/INTENTIUS/gitlab-warden). The agent skill, the policy examples, and the CI templates live in it, and setup ends with a warden pipeline in your group, so you'll have the repo anyway. - A GitLab personal access token with
apiscope: Owner on the groups you'll govern and Maintainer or above on projects (the setup guide walks through creating one). - Node 22+.
About ten minutes gets you to a first dry-run plan. The quickest probe needs no clone at all:
# Dry-run: reads only, prints a plan, changes nothing.
npx @intentius/gitlab-warden reconcile --config governance.yml --token-env GITLAB_TOKEN --mode dry-runThe npm package is also what your pipeline installs later (the
CI guide). Add --base-url for self-managed (defaults to
gitlab.com). Full config + flags in Usage below.
Teams moving off GitHub Actions can start with
gitlab-warden migrate .github/workflows/, which translates the existing
workflows into a stitched .gitlab-ci.yml (the migration guide).
You declare desired state in YAML (selective-by-omission: an absent field is
never read, diffed, or touched); warden diffs it against the live GitLab API
and, in apply mode, converges it, guarded so a typo can't mass-delete.
It's a single binary + a YAML file in CI: no state file, no HCL, no provider toolchain to stand up. The point is governance-as-code without the weight, covering the full GitLab governance surface in one place.
Warden is stateless. It diffs against live state and reconciles, so there is nothing to drift or import and no lock to hold, and correction is continuous: a reconcile loop keeps running rather than applying once. Declarations are selective-by-omission with ownership-gated deletes, which lets you manage a slice of a large instance without claiming the rest. Dry-run is the default mode, and a removal cap guards the apply path. Premium/Ultimate endpoints that 403 on read are tolerated and skipped, never fatal.
GitLab push rules aren't version-controlled, and their inheritance is broken: rules are copied at project creation and never propagated, so a changed group rule never reaches existing projects (each one gets fixed by hand). A reconcile loop that re-asserts declared push rules across a whole group tree fixes that continuously, and it is one clear example of the model warden applies across the entire governance surface.
| Scope | Cycles |
|---|---|
| Group | settings · members · subgroup/project provisioning · variables · webhooks · push rules · deploy tokens · access tokens · protected environments · integrations · compliance frameworks · security policies · member roles |
| Project | settings · members · protected branches · protected tags · protected environments · push rules · MR approvals · variables · webhooks · integrations · deploy keys/tokens · access tokens · advanced protections (job-token scope) · security policy attachment |
| Instance (self-managed) | application settings · instance CI/CD variables · system hooks · custom member roles |
REST for most of it; GraphQL for the few surfaces that require it (compliance frameworks, security-policy attachment). The Ultimate-only GraphQL cycles are best-effort (unvalidated against a live Ultimate instance; the e2e runs CE).
npx @intentius/gitlab-warden reconcile \
--config governance.yml \
--mode dry-run \
--token-env GITLAB_TOKEN \
--base-url https://gitlab.example.com # omit for gitlab.com# governance.yml — declared nodes, keyed by full path
nodes:
acme/platform:
kind: group
groupSettings: { description: "Platform team", visibility: private }
members:
- { user: alice, accessLevel: owner }
pushRules: { preventSecrets: true }
acme/platform/api:
kind: project
projectSettings: { mergeMethod: ff, topics: [go, service] }
protectedBranches:
- { name: main, pushAccessLevel: 40, mergeAccessLevel: 30 }--mode dry-run (default) prints the plan; --mode apply converges it,
with the per-collection removal cap bounding deletes per apply (see
POLICY.md) and tier-gated endpoints handled as described above.
The package ships a forge-governance member kind for chant workspaces
(chant#3180). A repo that holds a governance policy declares it
as a member, so chant workspace ls and chant workspace graph list the policy beside the rest of the estate.
{
"pins": [{ "package": "@intentius/gitlab-warden", "version": "<this version>" }],
"members": [{ "name": "forge", "dir": "governance", "kind": "forge-governance" }]
}The kind is data in workspace-kinds.json, exported at @intentius/gitlab-warden/workspace-kinds. chant reads it without
importing the package.
The kind needs chant >= 0.124.96: its memberFile arrived in 0.124.48, its graph.reader in 0.124.49 and its
drift.reader in 0.124.96, and an older chant drops the kind with WSP002. npm test validates workspace-kinds.json against chant's
workspace-kinds.schema.json, and the graph the reader draws for a sample policy against chant's graph schema.
| Part | Value |
|---|---|
| Probe | governance.yml, or the older governance.yaml, directly in the member's directory |
| Member file | governance.yml must pass schemas/governance.schema.json. chant workspace check reports a missing file, a file that does not parse, or a field the schema does not know as WSP012, so a member that still has governance.yaml gets WSP012 until the file is renamed |
| Outputs | repos, the project nodes in nodes, and teams, the group nodes in nodes, for member links |
| Graph | graph.reader names dist/graph-reader.mjs, which turns governance.yml into graph IR with no GitLab call (a member with only governance.yaml is read with a deprecation note on stderr). A group is a team and a project is a repo. Nodes are the top-level namespace as the org, the groups, the projects, each project's protectedBranches entries and each integrations entry as an app. Edges run from a group to the projects and subgroups below it, from a rule to its project and from an app to the group or project it is on. GitLab has push rules rather than rulesets, so there are no ruleset nodes. It draws the policy as declared, with no live state |
| Drift | drift.reader names dist/drift-reader.mjs, which chant workspace drift --member <name> runs. See Drift in a chant workspace |
The schema is stricter than the loader: the loader drops a field it does not know, and the schema refuses it, so a
misspelled field fails chant workspace check before a reconcile silently leaves it unmanaged.
chant workspace drift --member <name> reads a governance member through the kind's drift reader, which needs chant
>= 0.124.96 (KIND_DRIFT_READER_FLOOR); an older chant can't read the kinds file's drift block. The reader loads
the member's governance.yml, falling back to governance.yaml with a deprecation note and then to governance.ts.
Every cycle runs as a dry-run reconcile against GitLab, so the reader reads and never writes. It answers with chant's drift stream, engine
warden, read live-read. It runs inside chant's process and takes its credentials from the environment: the token
from GITLAB_TOKEN and the instance from GITLAB_BASE_URL, defaulting to https://gitlab.com.
There is one record per node the policy declares, at the graph reader's node id (team/<group>, repo/<project>,
protection/<project>/<branch>, app/<path>/<integration>), so chant colours the member's graph; an instance node,
which the graph does not draw, is instance/<path>. A node with no planned change under it is in-sync. A node with
planned changes is drifted, each change one attribute: an update gives <type>[#<key>].<field> with before the
declared value and after GitLab's. A create gives <type>[#<key>] with the declared value and a delete gives
<type>[#<key>] with the live one (group-settings.<field> and project-settings.<field> stand for a node's own
settings). Members and variables count under their group, project or instance, and hooks, push rules and the
other per-node settings follow the same rule. A protected branch and an integration are nodes of their own. A change under a node the graph does not draw (an owned protected
branch the policy does not declare) is a drifted record of its own. Variables, hooks and integrations carry no values, and neither do
deploy keys or tokens (sensitive: true).
A cycle that fails leaves its node's records not-observed with reason read-failed (or drifted with the failure
noted, where another cycle found drift), and a cycle the request budget skipped leaves every record not-observed
with reason not-reached, so a read that did not finish never reads as clean.
If the token is missing or the member has no policy, the read is refused with no-drift-read, and no call reaches GitLab. A
policy that does not load fails the read. --resource <node id> reads one declared node (its group or project is
reconciled alone); an undeclared one is refused with no-drift-read. --read other than live-read, and --stack,
are refused with read-unsupported.
The plan that gitlab-warden reconcile --plan-json <file> writes as a chant change-set part uses the same node ids. A
change to a node's own state has the bare id as its address and any other change has <node id>#<resourceType>[<key>],
so chant places plan entries and drift records on the same nodes. The
CLI reference has the details.
gitlab-warden reconcile --drift-issue builds the same records from a scheduled dry run and keeps one GitLab issue
open while they show drift, closing it once GitLab matches the policy. The flags and the scheduled workflow for this issue are described in the CLI reference (CLI.md) and
the CI guide (CI.md).
npm test runs the unit suite (mock-client, fully offline). The
e2e smoke suite
is fully hermetic. It stands up GitLab CE via Docker Compose and
provisions its own group, project, and users with no external account or
secrets. It exercises every cycle's read path (asserting it stays read-only)
and, behind an opt-in flag, a full apply smoke. Every CE-supported cycle
applies a policy and then re-converges to an empty plan; out-of-band drift
gets corrected on the next run, and nodes declaring owned perform a real
delete. Tier-gated cycles assert graceful degradation instead. The
cycle-by-cycle table lives in
e2e/README.md.
eval "$(npm run --silent e2e:up)" # compose up + mint token (GitLab CE is slow)
GITLAB_E2E_APPLY=1 npm run test:e2e:run
npm run e2e:downGitLab is a tree of nested groups with inherited membership rather than a
flat org. Membership is diffed against direct members (/members); the
effective roster (/members/all) is never consulted. An inherited
member is never treated as deletable drift (the DELETE would fail, since
the grant lives at an ancestor). The
scope and inheritance model documents the rules the membership
cycle follows.
This is the third warden built on the shared provider-agnostic reconcile
primitive in
@intentius/chant/reconcile. That
core also powers github-warden
and forgejo-warden.
gitlab-warden supplies the GitLab layer: a REST + GraphQL client with a configurable host
(self-managed or GitLab.com), the config and live-state types, and the
reconcile cycles with their GitLab diff().
| github-warden | forgejo-warden | gitlab-warden | |
|---|---|---|---|
| Hierarchy | flat org → repo | flat org → repo | nested groups → projects |
| Membership | direct | team-driven | direct + inherited |
| Auth | GitHub App | token, self-hosted | token, self-managed + SaaS |
| API | REST | REST | REST + GraphQL |
| Reconcile core | @intentius/chant/reconcile |
(same) | (same) |