The squash merge that resurrected a release
A release pull request merged with squash brought back a changeset that had already shipped. Six incidents from one evening of setting up a canary-to-main flow, and the rule each one produced.
In part 2 I described the release flow I now use in every repository: canary as the default branch, main as production, and a bot that opens the release pull request. It looks simple on paper. Setting it up on five repositories in one evening broke it, or showed it was already broken, six different ways.
None of these failures came from application code. They came from repository settings, merge buttons, permissions and workflow triggers, and the test suite can’t see any of those. Each story follows the same format: symptom, cause, and the rule it produced.
1. A release that should not exist
Symptom. quality-gate v0.3.0 shipped. A few minutes later, a release pull request for 0.4.0 appeared, listing changes that had already shipped in 0.3.0.
Cause. The release pull request (canary → main) had been merged with squash. The shared release workflow expects main to contain the canary commits, so it can fast-forward canary after the release. After a squash, it doesn’t. main had one new commit that carried the same changes as canary under a different history.
The workflow did what it was designed to do: it couldn’t fast-forward, so it opened a sync pull request from main back into canary. Merging that sync brought the changeset back.
Git merges by comparing each side with their common ancestor, and the common ancestor was older than the changeset:
- On
canary, the changeset file had been added. - On
main, the squash commit added it and the release commit deleted it. Compared with the ancestor, nothing changed.
One side added a file and the other side didn’t touch it, so Git kept the file. The consumed changeset was back on canary, and the release bot saw a pending release.
Rule. Merge commits only, in the repository settings and in both rulesets, so no one can pick squash from the dropdown. The release pull request now also closes itself when nothing is pending. Rebasing your own feature branch onto canary is still fine: the flow only needs main to contain the exact commits of canary.
2. canary vanished
Symptom. This site’s canary deployment stopped updating. Agents created branches from a canary that no longer existed on GitHub.
Cause. An earlier release pull request (canary → main) had been merged with Automatically delete head branches turned on. For GitHub, canary was the head branch of that pull request, so it deleted it like any feature branch. I lost nothing, since every commit was already in main. The deletion went unnoticed for two days.
Rule. canary is the default branch. GitHub never deletes the default branch, and it’s protected against deletion anyway.
3. “Protect main” was about to move to canary
Symptom. None, luckily. I caught this one before switching.
Cause. The existing ruleset targeted ~DEFAULT_BRANCH, not main by name. Changing the default branch to canary would have moved every protection to canary and left production unprotected.
Rule. Rulesets with explicit targets (refs/heads/canary, refs/heads/main), created before the default branch changes.
4. The bot couldn’t open the release pull request
Symptom. The release workflow failed with: “GitHub Actions is not permitted to create or approve pull requests.”
Cause. A repository setting, off by default: Allow GitHub Actions to create and approve pull requests.
Rule. It’s part of the setup checklist now, applied by a script along with the other settings, instead of found by a failing run.
5. The release job ran my full pre-push
Symptom. The release job ran checks that had nothing to do with releasing.
Cause. In CI, vp install runs the prepare script, which installs the git hooks. When the bot committed and pushed the release, my pre-commit and pre-push hooks ran inside CI, full verification included.
Rule. VP_GIT_HOOKS=0 in every bot job. Hooks are for people and agents working locally. CI already runs the checks once.
6. A red X on every release pull request
Symptom. Each release pull request showed a failed or pending check, even when everything was fine.
Cause. Pull requests opened by github-actions[bot] get their workflow runs held for approval. The check stayed blocked.
Rule. CI on pull requests runs only for pull requests into canary. The release pull request targets main, and its head, canary, was already checked when it was pushed. The bot’s sync pull request back into canary still waits for approval, but its content already passed on main.
What these have in common
Tests, linting and code review would have missed all six. The repository settings belong to the release flow as much as the workflow files do, but they live in a web UI where no diff shows them.
So the last step of the evening turned these rules into scripts: one that audits a repository’s settings against the convention, and one that applies them. The audit’s first run flagged a gap I had left myself, Dependabot alerts enabled on one repository out of four.
Takeaways
- Squash breaks any flow that expects
mainto containcanary. Disable it in the settings and in the rulesets. - Make the long-lived branch the default branch. GitHub won’t delete it.
- Target rulesets explicitly, and create them before you change the default branch.
- Bots need permissions that are off by default.
- Turn off git hooks in bot jobs.
- Script your repository settings and audit them, because the UI doesn’t show drift.
In part 4: how I proved that a refactor touching every page of this site changed nothing, and why the measurement had to be tested first.
Share this post