Keep your GitHub org and repos in a declared state, with guardrails and drift correction.
Full documentation lives at intentius.io/github-warden, with deep dives on these pages.
You declare the desired state of your org and repos in one YAML file
(selective-by-omission: an absent field is never read, diffed, or touched);
warden diffs it against live GitHub, runs safety guardrails, and either
prints the plan (dry-run, the default) or applies it. Deletes are planned
only in orgs you mark owned. Run it locally, on a schedule, or as a GitHub
Action.
From a checkout, Claude Code picks up the skill in
.claude/skills/github-warden automatically. Other agents can install it with
npx skills add INTENTIUS/github-warden, or by copying the skill directory
into ~/.claude/skills/. Then paste this prompt, filling in the placeholders:
Use the github-warden skill in this repo to help me set up governance for my
GitHub org <ORG>: author a governance policy file covering the settings I care
about (ask me which), explain whether I need a GitHub App or a token for those
cycles, then run a dry-run reconcile and walk me through the plan it prints.
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 an org owned in the policy.
- A clone of this repo (
git clone https://github.com/INTENTIUS/github-warden). The agent skill, the annotated policy examples, and the pipeline templates live in it, and setup ends with a governance pipeline running in your org, so you'll have the repo around anyway. The CLI is published to npm as@intentius/github-wardenfor those pipelines. - Auth. Org-level and token cycles need a GitHub App installed on your org
(App ID plus installation ID plus private key); repo-level reconcile and
auditcan run with a pre-minted installation token instead. See Auth and the App setup checklist. - Node 24+.
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/github-warden reconcile --config .github/governance.yml --token-env GH_TOKEN --mode dry-run| Command | What it does |
|---|---|
reconcile |
Run governance cycles: diff desired vs live, guardrail-check, dry-run or apply. |
audit |
Audit managed repos for security/correctness posture (chant's audit engine). |
report |
Aggregate cycle drift (+ optional audit + identity) into a compliance snapshot. |
github-warden reconcile [--config <path>] [--config-mode fold|run|check] [auth] [--mode dry-run|apply] [--cycles a,b,c] [--allow-guardrail-override] [--removal-cap-fraction <value>] [--plan-json <file> [--member <name>]]
| Flag | Meaning |
|---|---|
--config <path> |
Governance config (YAML, JSON or .ts). Default governance.yml, else governance.ts. |
--config-mode fold|run|check |
How a .ts policy is evaluated (default fold, which never runs it). |
--mode dry-run|apply |
Default dry-run. |
--cycles <name[,name...]> |
Subset of cycles to run (default: all). |
--allow-guardrail-override |
Apply even when guardrails trip. |
--removal-cap-fraction <value> |
removalDeltaCap threshold in (0,1] (default 0.25). |
--plan-json <file> |
Write the plan as a chant change-set part (lexicon github) for chant's change-set document. Each entry's address is its graph node id (repo/acme/api), or <node id>#<resourceType>[<key>] for a change under the node, so entries sit on the same nodes as the drift records. Dry-run only. |
--member <name> |
The member the --plan-json part names (default: the policy file's directory name). |
github-warden audit [--config <path>] [auth] [--fail-on none|merge-worthy|any]
Audits every repo declared in the config. Exits 4 when findings exceed --fail-on.
github-warden report --config <path> [auth] [--cycles a,b] [--audit] [--identity] [--out compliance.json] [--fail-on none|attention]
Runs the selected cycles in dry-run and prints a unified compliance
snapshot. Optional passes add an --audit sweep and an --identity
(service-account hygiene) check, while --out writes a committable JSON
artifact. With --fail-on attention the command exits 4 when anything needs
attention; nothing is ever mutated.
github-warden repos [--config <path>] [auth] [--org <name>] [--out <file>]
Writes the policy's org's repository list, archived repos included, as the
JSON chant workspace check --forge-repos <file> reads. See
CLI.md.
0 success · 1 guardrail block (apply) · 2 arg/config error · 3 runtime error · 4 audit/report threshold exceeded.
Each cycle reconciles one governance domain. Pass --cycles to run a subset, or
omit it to run all.
| Cycle | Reconciles |
|---|---|
branch-protection |
Classic branch protection rules (PUT …/branches/{b}/protection). |
org-settings |
Org settings — default repo permission, member repo-creation, public metadata. |
repo-settings |
Repo settings — visibility, features, merge settings, default branch, topics. |
membership |
Org members & roles (admins / members). Add/re-role; ownership-gated removal. |
teams |
Teams, team membership/roles, and team→repo permissions; rename-without-loss. |
rulesets |
Repo + org rulesets (the modern branch-protection replacement). |
security-features |
GHAS, secret scanning, push protection, Dependabot alerts + security updates. |
environments |
Deployment environments — required reviewers, wait timers, branch policies. |
secrets-variables |
Actions secrets (presence only — never values) and variables. |
dependency-hygiene |
.github/dependabot.yml presence + exact-content consistency. |
repo-baseline |
Ensure declared repos exist (create from a template if missing). |
token-governance |
Fine-grained PAT sweep — revoke org access for expired / over-lifetime / idle grants. |
token-approval |
Auto approve/deny pending fine-grained PAT requests against policy. |
Note: the GitHub Action exposes
reconcileandaudit.reportis CLI-only. The token cycles (token-governance,token-approval) and several org-level APIs require a GitHub App installation (they are not callable with a plain PAT).
Every field is optional; declare only what you want managed. A ready-to-edit
starter lives in examples/governance.yml.
The CLI's built-in YAML reader is block-style only — no flow style
({ } / [ ]), no multi-line scalars (| / >), no anchors. Use JSON for
anything richer, such as the multi-line dependabot.content.
orgs:
my-org:
# Org-level settings
settings:
defaultRepositoryPermission: read
membersCanCreatePublicRepositories: false
# Org members and roles
members:
- login: alice
role: admin
- login: bob # role defaults to "member"
# Teams (tree + membership + repo access)
teams:
backend:
privacy: closed
members:
- login: alice
role: maintainer
repos:
- name: api
permission: push
# Ensure these repos exist (create from a template if missing)
repoBaselines:
- name: new-service
template: my-org/service-template
private: true
# Org-level rulesets / secrets / variables
rulesets:
- name: protect-default
target: branch
enforcement: active
conditions:
ref_name:
include:
- "~DEFAULT_BRANCH"
rules:
- type: pull_request
secrets:
- name: ORG_DEPLOY_TOKEN # presence only; value provisioned out-of-band
variables:
- name: ENVIRONMENT
value: production
# Fine-grained PAT governance (GitHub App required)
tokenPolicy:
maxLifetimeDays: 90
maxIdleDays: 60
revokeExpired: true
tokenApproval:
allowedPermissions:
- repository:contents
default: deny
# Flag seat-consuming machine users (surfaced by `report --identity`)
machineUsers:
- ci-bot
- deploy-bot
repos:
my-repo:
description: My service
hasWiki: false
topics:
- api
- go
branchProtection:
- pattern: main
requirePullRequestReviews: true
requiredApprovingReviewCount: 1
requireStatusChecks: true
security:
secretScanning: true
secretScanningPushProtection: true
vulnerabilityAlerts: true
environments:
- name: production
waitTimer: 10
reviewers:
- type: Team
id: 42
# dependabot.content is a multi-line string — author that slice (or the
# whole config) in JSON; the built-in YAML reader has no `|` scalars.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, and
chant workspace drift --member reads its drift from GitHub.
{
"pins": [{ "package": "@intentius/github-warden", "version": "<this version>" }],
"members": [{ "name": "forge", "dir": ".github", "kind": "forge-governance" }]
}The kind is data in workspace-kinds.json, exported at @intentius/github-warden/workspace-kinds. chant reads it without
importing the package.
The kind needs chant 0.124.96 or newer. memberFile is read since 0.124.48, graph.reader since
0.124.49 and drift.reader since 0.124.96. An older chant drops the kind with WSP002. The test suite validates workspace-kinds.json
against chant's workspace-kinds.schema.json, the graph reader's output for the example policy against chant's
workspace graph.schema.json, and the drift reader's output against chant's drift-reader.schema.json.
| Part | Value |
|---|---|
| Probe | governance.yml 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 |
| Outputs | repos, the repos in orgs.<org>.repos, and teams, the teams in orgs.<org>.teams, for member links |
| Graph | graph.reader names dist/graph-reader.mjs, which turns governance.yml into graph IR with no GitHub call: nodes for the org, repos, teams, rulesets, branch protection rules and the GitHub Apps named as ruleset bypass actors, and edges for a team's access to a repo, a ruleset's reach over a repo, a rule's repo, an app's bypass and a team's parent. It draws the policy as declared. Needs chant 0.124.49 or newer (chant#4413) |
| Drift | drift.reader names dist/drift-reader.mjs, which runs a dry-run reconcile against GitHub and answers chant workspace drift --member. See Drift in a chant workspace. Needs chant 0.124.96 or newer (chant#5068) |
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. A member kind with a
memberFile needs chant 0.124.48 or newer (chant#3672); an older
chant fails the kinds file with WSP002.
chant workspace drift --member <name> reads a governance member through the kind's drift reader, which needs chant
0.124.96 or newer (KIND_DRIFT_READER_FLOOR). With an older chant the kinds file's drift block is unreadable, so the
kind is dropped with WSP002. The reader runs every cycle as a dry-run reconcile against GitHub, so it reads and never writes, and
returns chant's drift stream for the live-read read. It runs inside chant's process and takes its credentials from
the environment:
| Variable | Use |
|---|---|
GH_TOKEN |
The token, as --token-env GH_TOKEN reads it |
GITHUB_API_URL |
The API base, default https://api.github.com. GitHub Actions sets it, to the GHES API on GHES |
GOVERNANCE_APP_ID, GOVERNANCE_INSTALLATION_ID, GOVERNANCE_APP_PRIVATE_KEY |
App auth, used when GH_TOKEN is not set: the reader mints an installation token from the App ID, the installation ID and the private key (or GITHUB_APP_PRIVATE_KEY), as the CLI's App auth does |
chant reads a kind's drift.config only from this package's workspace-kinds.json, so a workspace cannot rename these
variables; set them in the environment chant workspace drift runs in.
Without credentials, or without a policy in the member's directory, the read is refused with no-drift-read. The
policy is the member's governance.yml, or governance.ts when there is no governance.yml, folded as reconcile
folds it. A policy that does not load fails the read.
Each record is one node of the member's graph, named by the graph reader's id, so chant colours the graph by it:
org/<org>, repo/<org>/<repo>, team/<org>/<team>, ruleset/<org>/<name> for an org ruleset,
ruleset/<org>/<repo>/<name> for a repo's, and protection/<org>/<repo>/<pattern>. A node with planned changes is
drifted, and each planned change under it is an attribute: an update gives one per field (repo[#api].hasWiki,
the declared value before and the live value after), a create the declared value with nothing live, a delete the live
value with nothing declared. The org node holds the org settings, members and token grants, and also the org's
secrets and variables. A team's members and repos count under the team. A repo's security
settings, dependabot file and environments count under the repo, and so do its secrets and variables. Secrets keep their path and never carry values. A node the plan leaves alone is
in-sync. A change under a node the policy does not declare, such as an owned delete of a repo the policy does not
list, is a record of its own. No cycle reads the ruleset bypass apps, which are graph nodes, so they get no record.
When a cycle errors for an org, that org's nodes are not-observed with reason read-failed (or drifted with
attributesUnobserved where other cycles found drift), and a cycle the request budget skipped makes every node
not-observed with reason not-reached, so an incomplete read never reads as no drift. --resource <address> reads one
declared node and reconciles only its org; --read other than live-read and --stack are refused with
read-unsupported.
reconcile --drift-issue keeps one GitHub issue over the same records, opened while GitHub drifts from the policy and
closed when it matches again (CLI.md, and the scheduled job in
CI.md).
Before any apply, warden runs safety checks and refuses dangerous changes
(override with --allow-guardrail-override):
| Guardrail | What it refuses or protects |
|---|---|
removalDeltaCap |
Refuses an apply whose deletes of any one resource type exceed 25% (default; --removal-cap-fraction) of that type's live managed entries in the declared collections (typo protection). Live entries of one type never dilute another's fraction. See POLICY.md for the canonical description. |
adminFloor |
Refuses if fewer than 2 org admins would remain. |
requiredAdmins / requireSelf |
Keep named admins (and the managing identity) from being removed. |
| rename-without-loss | A previously alias collapses a delete+create into an update, so a rename doesn't count as a deletion. |
Warden supports two mutually exclusive auth modes, and the token takes precedence when both are given.
- A pre-minted token via
--token-env GH_TOKEN(e.g. fromactions/create-github-app-token). - A GitHub App via
--app-id-envplus--installation-id-env, with the private key inGOVERNANCE_APP_PRIVATE_KEY(orGITHUB_APP_PRIVATE_KEY).
A GitHub App is required for org-level token policy/approval and several org administration APIs. The App setup checklist walks through creating it, the per-cycle permissions, and installation.
Warden also ships as a native GitHub Action, so a governance workflow needs no npm install step. The snippets below cover the common jobs; every input maps onto a CLI flag.
# Dry-run reconcile on every PR.
- uses: intentius/github-warden@b094e91b9313b2a44b6fa14781a4917d670f62ed # v0.7.0
with:
command: reconcile
config: .github/governance.yml
mode: dry-run
app-id: ${{ vars.WARDEN_APP_ID }}
installation-id: ${{ vars.WARDEN_INSTALLATION_ID }}
private-key: ${{ secrets.WARDEN_PRIVATE_KEY }}
# Apply on push to main.
- uses: intentius/github-warden@b094e91b9313b2a44b6fa14781a4917d670f62ed # v0.7.0
with:
command: reconcile
config: .github/governance.yml
mode: apply
app-id: ${{ vars.WARDEN_APP_ID }}
installation-id: ${{ vars.WARDEN_INSTALLATION_ID }}
private-key: ${{ secrets.WARDEN_PRIVATE_KEY }}
# Audit all managed repos — fail if merge-worthy findings exist.
- uses: intentius/github-warden@b094e91b9313b2a44b6fa14781a4917d670f62ed # v0.7.0
with:
command: audit
config: .github/governance.yml
fail-on: merge-worthy
app-id: ${{ vars.WARDEN_APP_ID }}
installation-id: ${{ vars.WARDEN_INSTALLATION_ID }}
private-key: ${{ secrets.WARDEN_PRIVATE_KEY }}The action accepts these inputs.
| Input | Required | Default | Description |
|---|---|---|---|
command |
no | reconcile |
reconcile or audit |
config |
yes | — | Path to governance config (YAML, JSON or .ts) |
config-mode |
no | fold |
How a .ts policy is evaluated: fold, run or check |
mode |
no | dry-run |
dry-run or apply (reconcile only) |
cycles |
no | all | Comma-separated cycle names (reconcile only) |
app-id |
yes | — | GitHub App ID |
installation-id |
yes | — | GitHub App installation ID |
private-key |
yes | — | GitHub App private key PEM — pass as a secret |
fail-on |
no | none |
none, merge-worthy, or any (audit only) |
allow-guardrail-override |
no | false |
Apply even when guardrails trip (reconcile only) |
The governancePipeline export (from the package root) generates a
.github/workflows/governance.yml that dry-runs on PRs touching the config
and applies on a schedule and on manual dispatch, pinned to a warden Action
SHA; the CI guide covers it in detail.
Releases go through chant release, set up in chant.config.ts.
just release (or gh workflow run publish.yml -f label=auto) starts
.github/workflows/publish.yml. The workflow picks the newest commit on main
whose checks passed and labels it from the conventional commits since the
previous vX.Y.Z tag. It cuts that commit and pushes the tag, then publishes
the package with npm provenance. The label is written into package.json at
release time, so a release needs no version commit.
just release-next prints the next label, and just release-plan prints what
a cut would do without writing anything. chant generates publish.yml, so
change chant.config.ts and run npx chant release workflow rather than
editing the file.
The package is published as @intentius/github-warden (scoped, under the
intentius npm org) via GitHub OIDC trusted publishing, with no npm token
involved, the same way the chant lexicons publish.
Unit tests (npm test) are fully mocked. Above them sit two gated e2e layers
(both under e2e/, both self-skipping — see e2e/README.md
for the cycle-by-cycle coverage table):
The hermetic compose smoke drives every cycle's full loop against a stateful
mock GitHub (dependency-free node, run via docker compose or directly). Each
cycle applies its policy slice and then re-plans to convergence, with
out-of-band drift corrected and deletes exercised under owned. The suite
also trips the removalDeltaCap block and walks the permission-gated 403 NOTE
path, and auth runs the real App JWT and installation-token flow against the
mock.
just e2e-up # or: node e2e/mock-github/server.mjs &
GITHUB_WARDEN_E2E_URL=http://localhost:8188 npm run test:e2e
just e2e-downThe real-App e2e is the non-hermetic layer: a gated, self-provisioning suite
that exercises every cycle against a real GitHub org via a real App
installation; nothing else validates the live API contract (especially the
App-only token cycles). Neither npm test nor PR CI includes it.
WARDEN_E2E_APP_ID=… WARDEN_E2E_INSTALLATION_ID=… \
WARDEN_E2E_PRIVATE_KEY="$(cat key.pem)" WARDEN_E2E_ORG=my-test-org \
npm run test:e2eThe suite provisions everything it needs: a throwaway repo
(warden-e2e-<run>) plus one Actions variable and one sealed-box-encrypted
secret, with the repo deleted on teardown, so nothing pre-existing is
required. When the WARDEN_E2E_* vars are unset, the whole suite self-skips.
Phase 1 always runs. Per cycle, it runs fetchLive + diff against the
provisioned repo/org and asserts that every HTTP call was a GET (fetchLive
never mutates) and that the diff composes a change set, which catches API
drift.
Phase 2 is opt-in via WARDEN_E2E_APPLY=1 and performs one apply through a
cycle (setting a repo topic), verified by re-fetch and cleaned up by the repo
teardown.
The App installation needs repository administration (create/delete repos)
and Actions secrets + variables read+write, plus the read scopes the cycles
touch. CI runs it nightly and on demand via .github/workflows/e2e.yml using
WARDEN_E2E_* repo secrets (never on PRs).
Once the App is created, installed on the test org, and its .pem downloaded
(the web-only steps), wiring the secrets and triggering a run is automated:
just e2e-setup <test-org> <app-slug> ./warden-e2e.pem # discovers app/installation id, sets the 4 secrets
just e2e-run # dispatch Phase 1 (add `true` for Phase 2)The provider-agnostic reconcile core (change-set model, generic collection diff,
guardrail framework) lives in @intentius/chant/reconcile;
github-warden builds the GitHub-specific cycles, live-state types, and
member-aware guardrails on top of it.