Use Cruft to Automatically Sync Template Changes to Dependent Repos

[TShDaub]

What is the problem or limitation you are having?

This issue proposes a solution for beeware/Python-support-testbed#127 and similar tickets, which highlights the challenge of managing project dependencies consistently across multiple repositories.

The problem

Currently, there’s no streamlined or automated way to keep project scaffolding (e.g. pyproject.toml, CI configs, linting rules, etc.) in sync across dependent repositories.

Describe the solution you'd like

Proposed Solution

Adopt cruft and GitHub Actions to manage and propagate changes from this repository (acting as a shared Cookiecutter template) to dependent projects. This enables us to automatically open pull requests in downstream repos whenever updates are made to the template.

Implementation Steps

Template Setup

Sync Mechanism

1. Add a GitHub Actions workflow (e.g. .github/workflows/propagate-template.yml https://gist.github.com/TShDaub/3de93a89afe0b65787b7aba210604b6a) that:

• Triggers on PR merges to main
• Clones downstream repos
• Uses cruft update to apply template changes
• Creates a new PR in each downstream repo if changes are detected

2. Authentication

• Generate a fine-grained Personal Access Token with
• contents: read/write
• pull requests: read/write

3. Save it in this repo

• Go to Settings > Secrets and variables > Actions > New repository secret
• Name it BOT_GITHUB_TOKEN

Downstream Repo Setup

For each downstream project, run
cruft link https://github.com/<org>/this-template-repo
Commit the generated .cruft.json to the repo so cruft update can track it.

Benefits

• Centralized template maintenance
• Automatic, traceable PRs to dependent repos
• Less manual overhead for managing shared project config

Describe alternatives you've considered

Manually creating over 72 individual pull requests across different repositories just to update linting rules.

Additional context

No response