From 7c041d2d2d938b4656fa1dc261ef5fddc90cf1e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Est=C3=A9fano=20Vechietti?= <311154804+estefano-vechietti-azion@users.noreply.github.com> Date: Tue, 3 Nov 2026 14:15:54 -0300 Subject: [PATCH] docs(commit-signing): document how pull requests merge under the rule Tested on a scratch repository with a ruleset that only requires signatures: squash merges pass with unsigned commits (GitHub signs the result), merge commits are refused unless every commit is signed, and rebase merges are always refused because GitHub cannot sign rebased commits. Existing history is not checked again. gh pr merge --squash refuses on its own pre-check while the API merge is allowed. Co-Authored-By: Claude Opus 5.5 --- docs/commit-signing.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/commit-signing.md b/docs/commit-signing.md index 143e3f9..bde1ec2 100644 --- a/docs/commit-signing.md +++ b/docs/commit-signing.md @@ -6,8 +6,28 @@ merge that carries a commit without a verified signature is rejected. The rule i Setup takes about five minutes and can reuse the SSH key you already push with. - Commits made in the GitHub web interface (web edits, squash merges) are signed by GitHub. They need nothing. +- Commits already on a protected branch are not checked again. The rule applies to what is pushed or merged from now on. - SSH signing needs git 2.34 or later (`git --version`). +## Merging pull requests + +How a pull request can be merged into a protected branch once the rule is enforced: + +| Merge method | Works? | Why | +|---|---|---| +| Squash and merge | Yes, even with unsigned commits on the branch | GitHub creates and signs the squashed commit | +| Create a merge commit | Only if every commit on the branch is signed | The branch's commits land on the protected branch as they are | +| Rebase and merge | No | Rebasing rewrites the commits and GitHub cannot sign them: `Rebase merges cannot be automatically signed by GitHub` | + +Repositories that rebase to keep a linear history should squash instead: a squash merge is linear too. + +`gh pr merge --squash` can refuse a pull request with unsigned commits, because the CLI reads the pull request as +blocked before asking GitHub. The merge itself is allowed: use the web interface, or the API: + +```bash +gh api -X PUT repos/aziontech//pulls//merge -f merge_method=squash +``` + ## 1. Have an SSH key The key you already push with works. To check whether one exists: @@ -147,5 +167,7 @@ The `reason` field from the verification command (step 4) usually names the caus | `unsupported value for gpg.format: ssh` | git older than 2.34 | Upgrade git (`brew upgrade git`) | | `agent refused operation`, or a passphrase prompt on every commit | Key not loaded in the ssh-agent | `ssh-add --apple-use-keychain ~/.ssh/id_ed25519` | | Push rejected with `Commits must have verified signatures` | An unsigned commit on the branch | Sign the commits again (Special cases) | +| Merge refused with `Commits must have verified signatures` | Merge commit with unsigned commits on the branch | Squash and merge, or sign the commits again | +| Merge refused with `Rebase merges cannot be automatically signed by GitHub` | Rebase and merge on a protected branch | Squash and merge (Merging pull requests) | Azion engineers with questions not answered here: ask `@aziontech/team-delivery-engineering`.