Agenda

1. The Repo Zoo Problem — what goes wrong at scale and why it's structural
2. Why existing tools fall short — the Day 0 / Day 365 gap
3. How Rhiza works — config, bundles, the sync loop, and Renovate
4. Getting started — setup, first sync, and token configuration
5. Living with Rhiza — sync PRs, customisation, and conflict resolution
6. The ecosystem — rhiza-hooks, rhiza-tools, and companion projects
7. Adoption — migrating existing repos and rolling out across a team

How every team starts

A new project? Run the generator.

cookiecutter gh:my-org/python-template

✓ CI workflow — wired up
✓ Makefile — ready
✓ Linting config — configured
✓ Test harness — set

Day 0 is great. Everything is consistent.

Then time passes.

The backtesting repo got a pre-commit hook the risk model never received.

The data pipeline still pins Python 3.9 — EOL since October 2024.

Three repos use Black. Two use Ruff. One uses both.

The reporting dashboard references a GitHub Actions runner deprecated eight months ago.

Nobody did this on purpose. It just happens.

Each repo drifted into a different breed — incompatible with the others, living in its own enclosure, expensive to maintain on its own terms.

The real cost

Every change made to one repo is a change not made to the others.

CVE in a GitHub Actions runner
You need to update 17 repos. You do 12, get distracted. Five months later, five are still vulnerable.

Python 3.9 reaches end-of-life
You update the active repos. The legacy repos drift on, unpatched.

Team decides to standardise on Ruff
Active repos updated. Legacy repos still run Black. "Our standard" is now a fiction.

The hidden tax

The problem is not just drift — it is the ongoing cost of managing inconsistency.

Every shared infrastructure decision multiplies by your repo count.

At 20 repos, a 15-minute task becomes an afternoon. At 50, it becomes a week.

The coordination problem

Who owns shared infrastructure?

• DevOps pushes a new CI standard → who updates the 30 repos?
• Security mandates a new linting rule → how does it reach everyone?
• A CVE appears in a GitHub Actions dependency → who's responsible?

There is no clean answer without a system. Everyone assumes someone else is handling it.

The classic response — write a runbook, send a team email — doesn't scale.
Documentation tells people what to do. Rhiza opens a pull request.

The tools we reach for

The Day 0 / Day 365 gap

All of these tools were designed to solve the Day 0 problem:

Getting a new project off the ground with sensible defaults.

None were designed for the Day 365 problem:

Keeping twenty existing projects aligned as shared infrastructure evolves.

Template systems treat configuration as something you set up once.
But configuration is not a one-time decision — it is ongoing infrastructure.

The insight

Born from experience at a large sovereign wealth fund: dozens of Python repos, multiple teams, no mechanism to stay aligned. The problem was not carelessness — it was structural. One-shot scaffolding produces drift by design.

Treat the update as a pull request, not a push.

Instead of forcing changes into downstream repos, Rhiza opens a PR in each one:

• Clean diff of what changed in the template
• Owner reviews, adapts if necessary, merges
• Opt-in per repo — systematic across the organisation

The sync is not a bulldozer. It is a proposal.

Three actors

The config file: .rhiza/template.yml

repository: Jebel-Quant/rhiza   # Which template repo to sync from
ref: v0.8.0                      # Which version (pinned tag — recommended)

templates:                        # Named bundles of files to include
  - core
  - github
  - tests
  - renovate

exclude: |                        # Files you own locally — never overwritten
  ruff.toml
  Makefile.local

One file, under version control. That's all Rhiza needs.

Your org's fork

The canonical template is Jebel-Quant/rhiza. For most teams the right setup is:

1. Fork Jebel-Quant/rhiza into your organisation
2. Customise — add your org's runners, secrets, standards
3. Point all projects at your-org/rhiza in template.yml
4. Pull upstream when you're ready — nothing flows through without your review

Bundles — named groups of files

core is always required. All others are optional.

What's in the github bundle

None of these need to be written manually.
They arrive via uvx rhiza sync and stay current via the sync.

The sync loop

1. Fetch — reads template.yml, pulls matching files from the template repo at ref
2. Diff — compares what was fetched against what's currently in your project
3. Review — if anything changed, opens a pull request with the diff
4. Commit — you review the PR and merge it (or close it if not relevant)

Runs automatically on a weekly schedule via GitHub Actions.
On-demand: make sync or uvx rhiza sync.

Renovate — closing the loop

Without Renovate, the ref: pin is frozen. Projects drift behind the template silently.

Two separate PRs: should we upgrade? then here's what changed.

The ref: pin in depth

ref: v0.8.0   # pinned tag — recommended for all production repos
ref: main     # tracks latest commit — useful during template development only

Pinning to a tag gives you:

• A known, auditable version — you can see exactly what each project is running
• Safe upgrades — Renovate proposes the bump, you review before it lands
• Easy rollback — if v0.9.0 breaks something, the cause is unambiguous

Tracking main delivers template changes immediately with no review step. Use only when actively developing the template. Never in repos others depend on.

Four commands

# 1. Install uv (skip if already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Initialise — writes .rhiza/template.yml interactively
uvx rhiza init

# 3. Sync — fetches template files and writes them into the project
uvx rhiza sync

# 4. Install dev environment
make install

That's it. Your project is now Rhiza-managed.

What rhiza init asks

Running uvx rhiza init walks you through three questions:

? Template repository (GitHub owner/repo): Jebel-Quant/rhiza
? Template ref (tag, branch, or commit):   v0.8.0
? Bundles to include:                      core, github, tests, renovate

The result is .rhiza/template.yml — one file, under version control, that describes everything Rhiza will manage in this project.

After init, run uvx rhiza sync to write the actual files.
Review the diff with git diff before committing.

What you get on day one

After syncing with core + github + tests + renovate:

.github/workflows/rhiza_ci.yml          ← CI: test on push and PRs
.github/workflows/rhiza_pre-commit.yml  ← Pre-commit checks in CI
.github/workflows/rhiza_sync.yml        ← Weekly template sync
.pre-commit-config.yaml                 ← Local commit hooks
ruff.toml                               ← Linting config
Makefile                                ← make test · make lint · make release
.python-version                         ← Pinned Python version
.editorconfig                           ← Editor consistency

None of this required manual configuration.

The one manual step — PAT_TOKEN

The sync workflow opens pull requests. GitHub requires a Personal Access Token for PRs that touch .github/workflows/ files.

Create a fine-grained token:

GitHub → Settings → Developer settings → Personal access tokens (fine-grained)

Required permissions: contents: write, pull-requests: write, workflows: write

Add it as PAT_TOKEN in your repository secrets — or as an org secret to cover all repos at once.

Without PAT_TOKEN, the workflow falls back to GITHUB_TOKEN, which cannot write workflow files. Syncs that touch workflow files will silently produce no PR.

PyPI publishing — OIDC Trusted Publishing

The release workflow publishes to PyPI without a stored token, using OpenID Connect:

permissions:
  id-token: write   # required for OIDC — no PYPI_TOKEN needed

On PyPI: Publishing → Trusted Publishers → Add
Specify the repo name, workflow filename, and environment name. PyPI issues a short-lived credential at publish time.

Benefits:

• No token to rotate or accidentally expose
• Publish permission is tied to the specific workflow, not a person
• Revocation is instant — remove the trusted publisher on PyPI

Reading a sync PR

A sync PR is a standard git diff of template files that changed.

Green (added) — new template content your project doesn't have yet.
Usually safe to accept.

Red (removed) — content removed from the template.
Check whether anything you depend on is being removed.

Changed — read carefully. Could be a workflow version bump, a lint rule adjustment, or a security fix.

The PR description explains what changed at a high level. If Renovate bumped the ref, check the template repo's release notes for the version you're upgrading to.

Accept, modify, or reject?

Accept as-is — CI workflow updates, runner version bumps, linting adjustments that apply cleanly and tests pass.

Modify before merging — the change applies but needs a small tweak for your project. Or: add a file to exclude: in template.yml before merging.

Close without merging — the change isn't relevant (e.g. Docker support in a project that won't use containers).

Closing is fine. The next sync will re-open the PR
if the template still differs from your project.

Customising safely

Never edit template-managed files directly unless you also add them to exclude:.
Your change will be overwritten on the next sync.

Handling conflicts

A sync PR conflicts when you have edited a template-managed file locally.

Option 1 — Accept the template version
Discard your local change. Clean, but you lose your customisation.

Option 2 — Keep your version and exclude
Add the file to exclude: in template.yml, resolve the conflict in your favour. You now own that file permanently.

Option 3 — Merge both changes manually
Take what's useful from the template update and your local edit. Most effort, cleanest long-term result.

If you find yourself regularly in option 2 or 3 for the same file, that file belongs in exclude:.

The exclude list in practice

exclude: |
  ruff.toml                            # our lint rules differ from template defaults
  .github/workflows/rhiza_ci.yml       # we use a custom test matrix
  Makefile.local                       # project-specific targets

Exclude deliberately, not defensively.

Every excluded file is a file you are now responsible for — including applying security fixes the template would otherwise deliver automatically.

Audit your exclude list when bumping the template version. Ask: "Does the new template version of this file contain anything I should merge in manually?"

rhiza-hooks — pre-commit checks

rhiza-hooks ships pre-commit hooks that catch config errors before they reach CI:

Runs on every git commit. The same checks run in CI via rhiza_pre-commit.yml.

rhiza-tools — release and project utilities

uvx rhiza-tools <command> — or via make:

The Rhiza ecosystem

Who's using it

The Rhiza tools themselves — rhiza-cli, rhiza-hooks, and rhiza-tools all sync from rhiza. The system eats its own cooking.

External projects:

GitLab support

Rhiza works on GitLab with the gitlab bundle replacing github:

templates:
  - core
  - gitlab     # instead of github
  - tests
  - renovate

What changes: CI workflows become .gitlab-ci.yml pipeline files. The sync job runs as a scheduled pipeline. Renovate opens merge requests. PAT_TOKEN → GitLab Personal Access Token with api scope.

What doesn't change: template.yml, renovate.json, all tooling (rhiza-cli, rhiza-tools, rhiza-hooks).

Starting fresh vs. migrating

New project — the easy case:

uvx rhiza init && uvx rhiza sync && make install

Done. Rhiza-managed from day one.

Existing project:

uvx rhiza init           # creates .rhiza/template.yml
uvx rhiza sync           # writes template files — review the diff carefully
git add -p               # stage what makes sense
git commit -m "chore: adopt Rhiza template"

The first sync on an existing repo shows a diff. Some files may already match. Others may have local customisations — preserve those via exclude: before committing.

The migration path

1. Audit your current setup — list your CI files, linting configs, and Makefiles
2. Start conservative — begin with core only; add github once you've reviewed the workflow files
3. Exclude what you own — add locally-maintained files to exclude: before syncing
4. Review the first sync PR carefully — treat it as a code review, not a forced update
5. Add Renovate — add the renovate bundle and install the GitHub App
6. Expand bundles gradually — add tests, docker, etc. as your team gains confidence

Don't try to adopt everything at once. The goal of the first PR is to get Rhiza in place with minimal disruption.

Rolling out across a team

Week 1 — Pick one low-risk repo as your pilot. Adopt Rhiza, run a sync cycle, review the process with the team.

Weeks 2–3 — Add Rhiza to active projects. Fork the template into your org if you need custom standards.

Month 2 — Add Renovate org-wide. Enable the Dependency Dashboard. Review the first round of version-bump PRs together.

Ongoing — New projects start with uvx rhiza init. Legacy repos migrate at their next maintenance window.

Governance — One person or platform team owns the org's template fork. Changes go through PRs on the fork — reviewed before they propagate to all subscriber repos.

Key takeaways

1. Drift is structural — it is the default outcome of one-shot scaffolding, not a failure of discipline.

2. Existing template tools solve Day 0. Rhiza solves Day 365.

3. The PR model is the key insight. Systematic coverage, opt-in per repo, auditable history.

4. Setup is four commands. Ongoing maintenance is reviewing a weekly PR.

5. You stay in control. exclude:, extension files, and org forks give full flexibility.

6. Renovate closes the loop. Without it, the ref: pin is frozen and drift returns.

7. Adoption is gradual. One repo at a time, one bundle at a time.