Repo Blueprint
GitHub repositories that test, release, secure and update themselves — from one copier copy.
Repo Blueprint is a Copier template for eight kinds of projects: Home Assistant integrations, Nextcloud apps, GitHub Actions, Python and Node packages, Chrome extensions, container images and repositories without a build. A new repository starts with more than 30 workflows, and a bot brings it up to every new release of the blueprint.
- Tested on every change.
scripts/check.sh runs the same checks on your machine and in the CI, with full coverage of the code. The PR coach explains every check that fails, and the fix bot commits what a command can fix.
- Released and signed by a bot. Merging the release pull request publishes the release with its SBOM and the signed provenance of SLSA Build Level 3, and then verifies it as its users can.
- Secure from the first commit. CodeQL, OpenSSF Scorecard, a secret scan and an audit of the workflows run from the start, every action is pinned to a commit hash, and about 90 to 100 answers of OpenSSF Best Practices are filled in.
- Up to date by itself. Renovate updates the dependencies, the settings bot keeps the settings as code, and the blueprint bot brings every release of the blueprint as a pull request that its checks test before it merges; each public repository made with the blueprint takes every release this way.
The website of the blueprint has the guide and a page for each group of what a new repository gets, in English and German, with the comparison with other templates, a page for each kind of project, the questions and answers, the troubleshooting, the architecture, the reference of every question, variable and secret, the roadmap, the security design, the automation, the decisions and the dashboard.
💛 If the blueprint is useful to you, you can support its development. Deutsche Fassung.
Start a repository
Git, Python 3.12 or later, uv and GitHub CLI 2.48 or later, signed in as an administrator of the account or organization that will own the repository (gh auth login):
uvx --from copier==9.19.1 copier copy gh:Dennis-Otto/repo-blueprint my-project
cd my-project
python3 .github/blueprint.py create
With pipx in place of uv, the first line is pipx run --spec copier==9.19.1 copier copy gh:Dennis-Otto/repo-blueprint my-project, and a Copier of your own, Copier 9.8 or later, runs copier copy gh:Dennis-Otto/repo-blueprint my-project; on Windows, py -3 runs Python in place of python3. Copying runs no code of the blueprint: the template has no tasks, migrations or Jinja extensions, so Copier needs no --trust.
Copier asks for the name, a one-sentence description, the kind of project, the GitHub account or organization that owns it, the license (MIT, MIT-0, BSD-3-Clause, Apache-2.0, GPL-3.0-or-later or AGPL-3.0-or-later), a few details of the kind and the release app of the owner, which may stay empty until the checklist has registered it. The homepage is the website that the Docs workflow publishes on GitHub Pages, unless you name another or none, and the README, the About box, the issue forms, the manifest of an integration and appinfo/info.xml of an app link it; each kind starts with topics of its own, such as home-assistant, hacs for an integration, which HACS needs to list it. Copier refuses an answer that would break a file: a description or a name with """, */, ]]> or a backslash, which would end a docstring of Python, a comment of TypeScript or the CDATA of appinfo/info.xml, a Nextcloud app id that the App Store doesn't take, and topics that GitHub doesn't.
create makes the repository of the copy, with no checkout of the blueprint: every copy brings blueprint.py in .github/. It takes the owner and the name from the answers of Copier, and its preflight first checks Python, Git, GitHub CLI and its sign-in, the owner and the name; a finding marked with ✘ stops it before anything is made, with the command that fixes it. Then create runs git init --initial-branch=main, commits the files with a sign-off, creates the repository with gh repo create and pushes to it, public unless you add --private (green on GitHub Free too), then applies the settings as code and prints the checklist: what is left for a person, such as the release app and the secrets, and which steps are done. --dry-run prints the preflight and the commands and runs none. A run that stopped midway goes on where it stopped when you run create again. A folder that pushes to another repository is no new copy, and create refuses it. The troubleshooting explains each finding of the preflight. Every workflow runs on main, so settings check names a repository whose default branch has another name.
Made with the blueprint
Six public repositories follow the blueprint, each with code of its own and the checks and bots of the blueprint; every release of the blueprint reaches them as a pull request:
- HomeDarts for Autodarts, a Home Assistant integration: local real-time board control, games, tournaments and statistics, without a cloud account.
- Player Switch for Autodarts, a Chrome extension in TypeScript: a shared Autodarts display where everyone plays under their own account and a tap on a tile switches players, without signing in again.
- Issue assistant, a GitHub Action: a first analysis of every new issue by an AI that only reads, checked by a job without AI before it posts.
- Paperless Sync, a Nextcloud app: the documents of Paperless-ngx in Nextcloud Files, by correspondent, type and year.
- Paperless Unified Search, a Nextcloud app: the full-text search of Paperless-ngx in the unified search of Nextcloud.
- dennis-otto.github.io, a repository without a build: the website with every project of its owner.
The dashboard shows each of them at a glance: the release of the blueprint it is on, its checks, its releases and its Scorecard.
Why Repo Blueprint
- Rather than a template repository of GitHub: Use this template copies the files once, without the settings, and nothing follows them later. The blueprint sets the rulesets, the security and the environments as code, and brings every improvement as a pull request.
- Rather than Cookiecutter and cruft: the hooks of a Cookiecutter template run code on your machine, and
cruft update waits until someone runs it. Copier runs none of the blueprint's code, so it needs no --trust; blueprint.py create, which you run next, is a file of the copy that you can read first. And the bot of the blueprint updates every repository by itself.
- Rather than another Copier template, such as copier-uv or scientific-python/cookie, which serve Python projects well: the blueprint brings one standard to Home Assistant, Nextcloud, GitHub Actions, Node and containers too, with signed releases of SLSA Build Level 3, SBOMs and VEX, and tests each release on every kind and on the real repositories before it rolls out.
- Rather than projen: projen writes the files of a project from code that runs at every synthesis, above all for TypeScript, AWS CDK and jsii. The blueprint needs no code of its own in the project: it keeps its own files current and leaves those of the project to you.
The comparison puts them side by side, also where another tool fits better.
Kinds of projects
| Kind | Stack | Checks | Delivery |
|---|
| Home Assistant integration | Python 3.14, pytest-homeassistant-custom-component | Ruff, mypy, tests, HACS, hassfest | a zip asset for HACS, verified as HACS installs it |
| Nextcloud app | PHP 8.2 and newer, the tools on PHP 8.3, Composer | php-cs-fixer, Psalm with its taint analysis, PHP 8.2 for the code and its packages, PHPUnit in random order with full coverage | signed package to the App Store |
| GitHub Action | Python 3.12 of the runner, composite action | Ruff, mypy, tests, a run of the action | release tags and a moving major tag |
| Python package | Python 3.12, Hatchling | Ruff, mypy, tests, build | PyPI, trusted publishing |
| Node package | Node 24, TypeScript | Biome, tsc, node:test with full coverage, pack; npm without install scripts | npm with provenance |
| Chrome extension | Manifest V3, TypeScript | Node's, the manifest, Chrome for Testing | Chrome Web Store, without a stored secret |
| Container image | Alpine by digest | Hadolint, build, self-test | GHCR, multi-arch, with SBOM and provenance |
| Repository without a build |
Every kind starts with a small working example and its tests, to replace with the real code, and has a page of its own on the website: what it gets, the checks its pull requests need, its delivery, its checklist and the one line that copies it.
How a repository looks after itself
Every change, yours or a bot's, is a pull request that merges once every check passes, and the release bot makes a signed release of what reaches main; three bots keep the repository current on their own. In the pictures, blue is the blueprint and its bots, orange is you and what is yours, and green is what comes out.
The website of every repository shows all of it on the page Automation, which it writes from the workflows at every build: what each one does and what starts it, which checks a pull request needs, and which workflows hold a secret.
What a new repository gets
Each group has a page of its own, with what runs, the files that run it and the details.
- Checks:
scripts/check.sh runs the tests with full coverage, the types, the lint and the packaging, the same locally and in the CI.
- Lint: The workflows, the license of every file, the Markdown, and the spelling and style of the changed documents.
- Coverage: The report of a pull request compares the coverage of each file with that of
main.
- Fast checks: A scanner runs only in the pull requests that change what it reads, and the rest of the scans every week.
- PR coach: Every check that fails says what it found, why that matters and how to fix it, in one comment that follows every push, also on forks.
- Fix bot: A check that fails fixes what a command can fix, such as the format of the code, and commits it onto the branch.
- Flaky tests: Failed test jobs run once more, and a job that passes then is reported in one issue.
- Cancelled checks: A required check that a late run for an older commit cancelled starts again by itself.
- Failed releases: The release of a merge that fails for a moment runs its failed jobs once more.
- Bot health: A bot that fails on
main tries once more where that can help, and otherwise keeps one issue per workflow open, unless the workflow keeps its own.
- Mutation tests: Every week, thousands of small changes of the code show which of them the tests don't notice.
- Fuzzing: A Python package or a GitHub Action fuzzes every target in
fuzz/, in pull requests and every week.
- Property tests: The property tests of Python and Home Assistant projects run every night with new random inputs.
- Releases: A pull request with the next version and its changelog, and signed releases with provenance and SBOMs.
- Security: CodeQL, OpenSSF Scorecard, the review of the dependencies and the scanners of each kind of project.
- App Store: A Nextcloud app registers its id with its certificate, once, by hand.
- Dependencies: Renovate updates the dependencies a few times a day, as the release app of the owner.
- Updates: Right after every release of the blueprint, and every week, the blueprint bot opens a pull request with
copier update.
- Upstream: A Nextcloud app gets a pull request that raises
max-version once a new major version of Nextcloud passes every check.
- Issues: The issue assistant, an AI that only reads, analyses every new issue, labels it and finds duplicates.
- Welcome: A person's first pull request gets a comment with what helps it along.
- Area labels: Every pull request gets the labels of the areas whose files it changes.
- Branches: The branch bot brings the pull requests that wait for auto-merge up to date with
main, one at a time.
- Clean-up: Every week, the merged branches and the caches of closed pull requests go.
- Dashboard: One page shows every repository of the owner, the release of the blueprint it is on and the state of its checks.
- Website: The documentation in
docs/ as a website with search and a light and a dark theme, in English and German.
- Diagrams: Every diagram is a picture of its Mermaid source, so that the GitHub app shows it too.
- Screenshots: A bot renews the pictures of the project, only when their pixels change.
- Settings: Merges, rulesets, security, Actions, environments, variables and labels in
.github/repository.toml, which the settings bot applies.
- Community: README, contributing guide, code of conduct, security policy and the security design of the software.
- Development: A dev container for VS Code and Codespaces, and a hook that runs the checks before every push.
- Coding agents: The rules of the repository for Claude Code, Codex, GitHub Copilot and Cursor, in
AGENTS.md.
- Tools:
scripts/check.sh, scripts/diagrams.sh and scripts/social-preview.sh, the same in every repository.
Set up a repository
What a person does once: the release app of the account and its defaults, the secrets and the delivery of each repository, and the way an existing repository takes the blueprint. The guide walks through each of them.
How the blueprint works
The architecture shows how the blueprint is built, from copier.yml and template/ to the workflows that it shares with every repository and the tests that try each change on every kind of project, and the path of a release from a merge to the update of every repository. The reference describes every question of Copier and every variable and secret, written by reference.py from the sources that they describe, so that they can't drift. When something is unclear or doesn't work, see the questions and answers and the troubleshooting.
Where the blueprint is heading: the roadmap. What it protects and trusts: its security design.
Contributions are welcome: see CONTRIBUTING.md. Questions and problems: SUPPORT.md. Report vulnerabilities privately, as SECURITY.md describes.
License
MIT No Attribution: repositories made from the blueprint owe it nothing, not even a notice. Every file names its license in the machine-readable form of REUSE.
