Declarative, YAML-driven GitHub repository configuration

Describe how a repository should be configured in a YAML file; repo-management reads the live state, shows you the diff, and reconciles it through the GitHub API.

It is declarative and idempotent: re-running when nothing has changed does nothing. A section you don't mention is left unmanaged; a section you do declare is authoritative — it's the complete desired set, so anything on the repo not listed in it is removed.

Install

uv tool install repo-management    # or: pip install repo-management

Requires Python 3.14+. Authentication uses a GitHub token, read from $GITHUB_TOKEN (or --token); the token needs the scopes for whatever you manage (repo administration, Actions secrets, and so on).

Quick start

export GITHUB_TOKEN=ghp_...

cat > repos.yaml <<'EOF'
repos:
  - your-user/your-repo
settings:
  has_wiki: false
  delete_branch_on_merge: true
labels:
  - {name: bug,         color: d73a4a}
  - {name: enhancement, color: a2eeef}
EOF

repo-management validate -c repos.yaml   # check the YAML (no network)
repo-management plan     -c repos.yaml   # show the diff (read-only)
repo-management apply    -c repos.yaml   # reconcile (prompts before writing)

plan prints one line per change: + create, ~ update, - delete. Secret values are always redacted.

Declared sections are authoritative. A declared labels: section deletes labels not in the list; a declared collaborators: section removes unlisted direct collaborators. Start with plan and read the diff before your first apply.

Reference

CLI

validate, plan, apply, list-repos — flags, output formats, and errors.

Config files

Every section and field, authority semantics, and composing layers with extends.

Rulesets

Branch and tag rulesets: every rule type, conditions, and bypass actors.

What it manages

Section	Manages
`settings`	description, homepage, topics, visibility, feature toggles, merge options, default branch
`actions`	Actions enablement/policy (incl. selected-actions patterns), default workflow permissions, and workflow approval permission
`rulesets`	repository rulesets (branch/tag) with the full rule set, bypass actors, and ref-name conditions
`labels`	create/update/delete labels to match the listed set exactly
`collaborators`	add/re-permission direct collaborators; remove those not listed
`webhooks`	create/update/delete webhooks, matched by URL
`secrets`	Actions secrets (write-only); delete those not listed
`variables`	Actions repository variables; delete those not listed

Fleet automation

The nivintw/repo-management repository — the tool's home — is itself a working deployment: a control plane that manages its author's repositories with scheduled GitHub Actions, reconciling them to config/*.yml on every push and running a central Renovate instance scoped to exactly that fleet via repo-management list-repos --format names. It doubles as a reference for running the tool this way.

Development

Clone the repository, then:

uv sync                      # create the venv + install everything
uv run pytest                # tests + coverage (gate: 90%; currently 100%)
uvx prek run --all-files     # the full quality gate (ruff, format, REUSE, typos, …)