Skip to content

About

Reconcile GitHub orgs and repos to their declared state. Dry-run by default, ownership-gated deletes, and a removal cap.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

127 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

github-warden

ci e2e npm

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.

Set up with an agent

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.

What you need

  • 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-warden for 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 audit can 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

Subcommands

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.

reconcile

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).

audit

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.

report

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.

repos

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.

Exit codes

0 success · 1 guardrail block (apply) · 2 arg/config error · 3 runtime error · 4 audit/report threshold exceeded.

Cycles

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 reconcile and audit. report is 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).

Config format

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.

As a chant workspace member

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.

Drift in a chant workspace

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).

Guardrails

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.

Auth

Warden supports two mutually exclusive auth modes, and the token takes precedence when both are given.

  1. A pre-minted token via --token-env GH_TOKEN (e.g. from actions/create-github-app-token).
  2. A GitHub App via --app-id-env plus --installation-id-env, with the private key in GOVERNANCE_APP_PRIVATE_KEY (or GITHUB_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.

Use as a GitHub Action

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)

CI workflow generation

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.

Releasing

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.

End-to-end tests

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-down

The 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:e2e

The 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)

Architecture

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.

About

Reconcile GitHub orgs and repos to their declared state. Dry-run by default, ownership-gated deletes, and a removal cap.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages