Context
Adopting this template's branch rulesets — which enable required_signatures and non_fast_forward on both main and develop, with an admin bypass (RepositoryRole: Admin, always) — in a pre-existing (brownfield) repository surfaces a migration gap.
Problem
When the repo's history contains commits made before required_signatures was enabled, the first develop → main release is blocked: the merge introduces those legacy commits and required_signatures rejects them.
The natural fix is to re-sign the legacy commits (e.g. git filter-branch / rebase with -S) and update develop. But that update is a non-fast-forward (history rewrite), and the develop ruleset's non_fast_forward rule rejects it:
remote: error: GH013: Repository rule violations found for refs/heads/develop.
- Cannot force-push to this branch
Crucially, the ruleset's admin bypass does not permit this force-push over git — GitHub appears to honor ruleset bypass only for UI/API operations, not git push --force. So even the repository owner cannot complete the re-sign without first manually relaxing the ruleset.
Impact
A maintainer adopting the template on an existing repo cannot land the first release until they discover they must temporarily disable the develop ruleset, force-push the re-signed history, then re-enable it. There is no guidance for this in the template.
Suggested fix
Document a "migrating an existing repo to required_signatures" procedure (README / AGENTS.md), e.g.:
- Re-sign divergent history (preserves trees + merge topology):
git filter-branch -f --commit-filter 'git commit-tree -S "$@"' -- <merge-base>..HEAD
- Temporarily set the
develop ruleset Enforcement to Disabled (Settings → Rules → Rulesets).
- Force-push the re-signed branch to
develop.
- Re-enable Enforcement.
Alternatively, clarify the bypass/force-push limitation and/or advise enabling required_signatures only on repos whose full history is already signed.
Observed while adopting the template in ptr727/Utilities (a brownfield repo).
Context
Adopting this template's branch rulesets — which enable
required_signaturesandnon_fast_forwardon bothmainanddevelop, with an admin bypass (RepositoryRole: Admin,always) — in a pre-existing (brownfield) repository surfaces a migration gap.Problem
When the repo's history contains commits made before
required_signatureswas enabled, the firstdevelop → mainrelease is blocked: the merge introduces those legacy commits andrequired_signaturesrejects them.The natural fix is to re-sign the legacy commits (e.g.
git filter-branch/ rebase with-S) and updatedevelop. But that update is a non-fast-forward (history rewrite), and thedevelopruleset'snon_fast_forwardrule rejects it:Crucially, the ruleset's admin bypass does not permit this force-push over git — GitHub appears to honor ruleset bypass only for UI/API operations, not
git push --force. So even the repository owner cannot complete the re-sign without first manually relaxing the ruleset.Impact
A maintainer adopting the template on an existing repo cannot land the first release until they discover they must temporarily disable the
developruleset, force-push the re-signed history, then re-enable it. There is no guidance for this in the template.Suggested fix
Document a "migrating an existing repo to
required_signatures" procedure (README / AGENTS.md), e.g.:git filter-branch -f --commit-filter 'git commit-tree -S "$@"' -- <merge-base>..HEADdevelopruleset Enforcement to Disabled (Settings → Rules → Rulesets).develop.Alternatively, clarify the bypass/force-push limitation and/or advise enabling
required_signaturesonly on repos whose full history is already signed.Observed while adopting the template in ptr727/Utilities (a brownfield repo).