repo-policy

Lightweight, declarative repository governance for GitHub. Define expected branch protection and ruleset configuration in YAML; audit, preview, and apply it locally or in CI.

Not a Terraform replacement — no state file, no backend. repo-policy is safe to adopt incrementally on a live repository: by default it only ever touches branches you declare, and never deletes anything you didn't ask it to manage.

Features

Status legend: ✅ shipped, available today · 🚧 built, not yet live · 🔜 planned next · 💡 planned later, unscheduled.

See ROADMAP.md for target versions and dates, and its "Explicitly not doing" section for things deliberately kept out of scope (a state file, a UI/dashboard, other Git providers, a central server).

Install

pip install repo-policy

Quick start

# policy.yml
version: 1

branches:
  main:
    pull_requests:
      required: true
      approvals: 2
      code_owner_review: true
    status_checks:
      required: [build, test]
    signed_commits: true
    linear_history: true
    allow_force_push: false
    allow_deletion: false

repo-policy validate
repo-policy audit --repo acme/widgets
repo-policy plan --repo acme/widgets
repo-policy apply --repo acme/widgets

CLI Reference

Token resolution order: --token → GITHUB_TOKEN → GH_TOKEN → gh auth token (a local gh CLI login, tried last and only as a convenience — see SECURITY.md). Repo resolution order: --repo owner/name → $GITHUB_REPOSITORY → the local git origin remote.

See ARCHITECTURE.md's "Apply Outcomes and Exit Codes" for the full preflight / mutate / verify breakdown behind apply's row above.

Schema & Validation

repo-policy fails closed on ambiguous or malformed policy.yml input rather than guessing what you meant (src/repo_policy/models.py, src/repo_policy/config.py):

• Unknown fields are rejected, not silently ignored — every schema model uses Pydantic's extra="forbid", so a typo like strcit: or secret_scaning: is a validation error at validate time, not a quietly-ignored no-op.
• No implicit type coercion — every model also sets strict=True: a quoted boolean (signed_commits: "true"), yes/no/on/off, or a numeric string in place of a real integer is rejected rather than silently coerced.
• Duplicate YAML keys are rejected — a custom YAML loader fails a policy file with two strict: keys, two entries for the same branch name, etc., instead of PyYAML's default silent last-key-wins behavior.
• pull_requests.approvals must be 0–6 — anything outside that range is rejected before any API call is made.

Supported fields:

Two cross-field rules are enforced at validation time, before any API call:

• allow_fork_syncing: true requires lock_branch: true on the same branch — GitHub silently resets allow_fork_syncing back to false otherwise.
• automated_security_fixes: true requires vulnerability_alerts: true, and secret_scanning_push_protection: true requires secret_scanning: true — GitHub rejects enabling either one before its prerequisite.

pull_requests.dismissal_restrictions/pull_requests.bypass_pull_request_allowances, when declared, must name at least one user, team, (or app, for the bypass field) — an empty allow-list is rejected outright rather than sent to GitHub, since it would be ambiguous between "no restriction" and "restrict to nobody." See docs/adrs/0005-nested-actor-list-fields.md for why.

repo-policy validate checks all of the above against a real policy.yml, entirely offline.

GitHub Action

Pin to an immutable full commit SHA — the same convention this repository's own CI uses for every third-party Action it consumes (see .github/workflows/ci.yml), and the general supply-chain hardening recommendation for any Action, including this one:

- uses: shipsolid/repo-policy@a4d736b7fa8268115f50e61b4398d8d6a7ee7e1a # v0.4.7
  env:
    GITHUB_TOKEN: ${{ secrets.REPO_POLICY_TOKEN }}
  with:
    config: .github/repository-policy.yml
    mode: audit

Every release tag here (v<version>) is an annotated tag object, not a direct pointer to a commit — so git rev-parse v<version> alone returns that tag object's own SHA, not the commit's, and pinning uses: to it would silently defeat the point of pinning to a commit. Peel through the tag to get the actual commit SHA to pin:

git rev-parse v<version>^{commit}

or find it at github.com/shipsolid/repo-policy/tags → click the release tag → the commit it points to. (Once the release-bot signing pipeline in SECURITY.md's "Release Signing" section is live — see its Release Pipeline Setup Checklist for current status — each of these annotated tags will also carry a verifiable SSH signature; that doesn't change which SHA to pin here.)

Convenience alternative — @v0: a floating tag tracking the current major version (the same convention actions/checkout and similar Actions use). Each release force-moves it to nest, unpeeled, directly on top of that release's own annotated tag object (v0 → v<version> → the release commit) — this nesting is what will let git verify-tag v0 keep verifying transitively against the release-bot's signature after every move, once that signing pipeline is live (see docs/ci-cd.md).

- uses: shipsolid/repo-policy@v0

@v0 is movable, not immutable. What it resolves to changes on every release without any corresponding change to your own workflow file to review — convenient for staying current automatically, but unsuitable anywhere change control requires a pinned, auditable dependency (the same full-SHA-pinning convention this repository's own workflows follow for every third-party Action they consume — see docs/ci-cd.md). Prefer the full-SHA form above unless you have a specific reason to track the moving tag instead.

secrets.GITHUB_TOKEN will not work here, in any workflow, no matter what permissions: you grant it — confirmed against a real repo. GitHub Actions' automatically-generated token has no permission scope covering branch protection or ruleset administration; that's a platform constraint, not something a workflow can opt into. Create a PAT with repo scope (classic) or Administration: Read and write (fine-grained), store it as a repository secret — REPO_POLICY_TOKEN above is just an example name — and reference that secret instead.

Self-governance

This repository governs itself with its own tool: .github/repository-policy.yml declares main's branch protection and repo security settings, and .github/workflows/policy-audit.yml runs repo-policy audit against it on a daily schedule, on every change to the policy file or that workflow, and on demand.

• The audit workflow is read-only (mode: audit) and needs a POLICY_AUDIT_TOKEN repository secret — a fine-grained PAT scoped to this repository only, with Administration: Read. That secret does not exist yet; creating it is a live-repo setup step for whoever holds admin access.
• .github/repository-policy.yml documents the intended branch protection for this repository — it has not yet been applied. Until repo-policy apply runs against the live repository (a manual, reviewed step — see SECURITY.md's Threat Model for why apply is never run unattended against a real repo from an untrusted trigger), it does not reflect live GitHub state.
• If a change to main's required status check ever leaves it unable to produce a passing required result — blocking the very fix that would repair it — see SECURITY.md's "Emergency Recovery" for the documented, auditable bypass procedure.

How it works

Every declared branch is diffed against live GitHub state and reconciled through one of two backends, selected per branch with enforcement: branch_protection | ruleset (default branch_protection). See ARCHITECTURE.md for the full data flow, safety model, and known v1 limitations, and docs/adrs/ for why it's built this way.

Exit codes

This mapping is shared by audit, plan, and apply alike:

More docs

• examples/ — default.policy.yml (a ready-to-use baseline for main, pick it up and go) and sample-repository-policy.yml (every field the schema supports, fully commented)
• ARCHITECTURE.md — design, data flow, safety model
• docs/adrs/ — why the key decisions were made
• docs/ci-cd.md — release pipeline, PyPI publishing, the v0 tag
• docs/test-strategy.md — what's tested, and what mocking alone can't catch
• docs/troubleshooting.md · FAQ.md · SUPPORT.md
• SECURITY.md — token permissions and threat model
• CONTRIBUTING.md · ROADMAP.md · CHANGELOG.md

License

MIT