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.

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. Repo resolution order: --repo owner/name → $GITHUB_REPOSITORY → the local git origin remote.

GitHub Action

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

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.

The floating tag tracks the current major version (v0 until a 1.0.0 release ships), the same convention actions/checkout and similar Actions use.

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

More docs

• 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