Skip to content

Questions and answers

The questions that come up most when a repository takes the blueprint. What to do when something doesn't work is on the page Troubleshooting, every question of Copier and every variable and secret in the reference.

Does the blueprint work for my own account or organization?

Yes, for every account and organization on GitHub. A repository made from it names nothing of the blueprint's owner but the links to the blueprint, and every bot acts as an app of yours. You bring two things: a release app, once for all of your repositories, which the checklist helps you register, and your defaults in Copier's settings file, so that each new repository asks only what is new. Renovate runs in a workflow of each repository or as the Mend Renovate app, by the answer renovate_runner. The page Your own account walks through every step, from the copy to a checklist without a cross.

Why do the bots need a release app?

What a workflow does with the token that GitHub gives it, GITHUB_TOKEN, starts no other workflow: a release or update pull request that it opened would run no checks, and a merge with it would start no release. The bots act as a GitHub App of yours instead, whose token starts the checks, may change workflows and creates the release tags, which only this app may create. Only the owner of an app has its private key, so the blueprint can't lend its own. Until the app is there, the bots say in their summary what is missing, rather than fail at a token.

How do I switch the AI of the issue assistant off?

Change the answer issue_assistant_ai and commit the update:

copier update --defaults --vcs-ref=:current: --data issue_assistant_ai=false

The settings bot then sets the variable ISSUE_ASSISTANT_AI to off, the environment issue-assistant asks for no secret, and SUPPORT.md tells reporters that no AI reads their issues. Labels, reminders, closing with the release and the commands of the maintainer work as before. Deleting the secret CLAUDE_CODE_OAUTH_TOKEN stops the AI at once as well, but the checklist then asks for it again. --data issue_assistant_ai=true turns the AI on later.

How do I stop the updates of the blueprint from merging themselves?

Set the repository variable BLUEPRINT_AUTOMERGE to off: every update of the blueprint then waits for you, with its notes and the files it changes in its description. Set it in [variables] of .github/repository.project.toml, which the settings bot applies, or under Settings → Secrets and variables → Actions → Variables. To let them merge themselves again, set it to on there, or delete the variable on GitHub, with gh variable delete BLUEPRINT_AUTOMERGE or on that page: the settings bot sets variables but never deletes one, so a line removed from the file leaves off in place. An update with conflicts always waits, and so does one whose auto-merge you switched off, which stays off.

The other bots that merge their own pull requests have switches of their own:

  • The upstream bot of a Nextcloud app waits with UPSTREAM_AUTOMERGE set to off.
  • Renovate merges what the rules of .github/renovate.json5 let it, which a rule with "automerge": false stops for the packages that it names; the weekly refresh of the lock files waits for you anyway.

Can a repository be private, and what does it cost?

Yes: python3 .github/blueprint.py create --private creates a private repository. Public repositories run GitHub Actions for free. A private one on GitHub Free has 2,000 minutes a month, and GitHub rounds every job up to a whole minute. The schedules of a project, and the runs that they start, come to about 20 runs a day, about 600 a month; the checks of the pull requests cost more, which is why the blueprint runs a check only where it can change a result and keeps the jobs few (decisions 0009 and 0027).

Some of what the blueprint turns on is free only for public repositories. For a private one, GitHub asks for a paid plan for rulesets and GitHub Pages, and for GitHub Advanced Security for code scanning, the dependency review and the push protection of secret scanning. Until then, settings apply names each part that GitHub refuses, and the checks that need them fail.

Which files may a project change?

Every file, and each change survives the updates:

  • The files of the project, such as the README, the changelog, the code, the tests, the manifests and the pages of the website, are never overwritten by an update. The reference lists their patterns, from _skip_if_exists of copier.yml.
  • The files of the blueprint, such as the workflows and scripts/check.sh, take the changes of each update: copier update merges them with the changes of the repository, line by line, and marks a conflict only where both changed the same lines.

So that updates rarely conflict, a project adds its own beside the blueprint's files rather than in them: its settings in .github/repository.project.toml, its checks in scripts/check-project.sh and scripts/check-site.sh, their explanations in .github/checks.project.toml, its notes for coding agents in .github/agents.project.md, and workflows in files of their own. A fix that every repository needs belongs in the blueprint, whose next release brings it to all of them.

How do I change an answer later?

Run copier update with the new answer and commit the update, such as for the topics:

copier update --defaults --vcs-ref=:current: --data "topics=python, pypi, cli"

--vcs-ref=:current: keeps the release of the blueprint that the repository is on, and --defaults takes every other answer from .copier-answers.yml. The settings bot applies what the answer changes in .github/repository.toml, such as a variable or the topics, after the merge.

How do I leave the blueprint?

Delete .github/workflows/blueprint-update.yml, and no update of the blueprint comes any more; the Rollout of the blueprint leaves a repository without the blueprint bot out. Everything else stays and works as it is, since it is a file of your repository: the workflows, the checks, the settings as code with .github/blueprint.py and the other bots. The license of the blueprint, MIT No Attribution, asks nothing of what you keep, not even a notice. Keep .copier-answers.yml if you might come back: copier update starts from the release that it names.

To pause the updates rather than leave, set BLUEPRINT_AUTOMERGE to off and leave the update pull request open; a newer release moves it on.