Merging without a queue
It works by making clashes impossible, not by testing every combination. A small bot of our own catches the few that remain. No Enterprise.
The rethink: 4 laws
- The path is the name. The folder names the context. The kernel puts that name in front of every URL, metric, alert, flag, MCP tool, table and event.
- A claim is a git conflict. Whatever two pull requests could both claim is a path or one line in a sorted list.
context.yamlholds a random id. GitHub refuses to merge a text conflict, on any plan. - No file every pull request edits. The kernel finds contexts; shared lists are generated and not committed.
- What others use only grows. A published contract is never edited. Retire first, delete later.
The breaks you saw, and the others (MEASURED, local git)
| Break | 20 Nov layout | With the 4 laws |
|---|---|---|
| same metric, two contexts | breaks main | impossible |
| same metric, same context | git conflict | git conflict |
| same context name | merges silently into one folder | git conflict |
| same route, two contexts | breaks main | impossible |
| same route, same context | git conflict | git conflict |
| same alert id, two contexts | breaks main | impossible |
| same alert id, same context | breaks main | git conflict |
| same free URL (an old or vanity address) | no rule existed (REASONED, not run) | git conflict (one claim file per address) |
| used dependency deleted | breaks main | red in its own pull request |
| published contract edited | silent | red in its own pull request |
| stale generated file, upgrade forgot files | red in its own pull request | red in its own pull request |
| retired dependency or contract deleted while an old pull request starts using it | breaks main | remains |
| two pull requests each add half of a call loop | breaks main | remains |
| context deleted while another adds a file to it | breaks main | remains |
| generator upgraded while another adds a context (committed generated files only) | breaks main | remains |
- Every pair, not just the examples: 62 possible changes, 1,891 pairs. 1,804 merged clean, 62 were git conflicts, 25 broke main. All 25 are the four "remains" rows: deletions, upgrades and new call edges. No unknown kind appeared. MEASURED
- Conflicts almost never cross contexts: 1 of the 1,498 pairs from different contexts conflicted (a deletion against a generator upgrade). MEASURED
- Correction to the earlier proof: a
context.yamlalone is not enough. Two identical ones merge silently, which is what a template produces. The random id is what makes it a conflict. MEASURED (case 2c)
The four that remain: our own merge bot (built and tested)
- You label a pull request
merge. - The bot joins it with the newest main.
- It runs the fast whole-repo check (names, needs, uses, generated files; add the compile step per language).
- It pushes exactly what it tested. If main moved meanwhile, it starts again.
- Red: it removes the label and says why.
| Test | Result | Tag |
|---|---|---|
| the four remaining breaks | all bounced; main green | MEASURED, local |
| 50 waiting pull requests | 50 merged in 12.4 seconds | MEASURED, local |
| a person pushes while the bot tests | retried; main green | MEASURED, local |
| same on GitHub, private repo | 2 to 4 seconds each; pull requests show "merged"; commits verified | MEASURED, GitHub |
| pull request with a git conflict | GitHub refused it (HTTP 405) | MEASURED, GitHub |
| a person skips the bot, no rules | main broke; a signed revert made it green in 1.5 seconds | MEASURED, GitHub |
| GitHub Team rule "only the bot updates main" | the button and an unlisted pusher were refused; the listed one merged | MEASURED, GitHub |
- The bug the test found: asking GitHub for "pull requests with label merge" lags behind a fresh label. The bot now reads the plain list. MEASURED, fixed
- Nobody rebases. The bot does the join. The pull request's own CI does not run again.
- Why it stays fast: it runs only the check that needs the whole repo. The full tests run on the pull request and again on main.
- Backstop: CI on main. Red blocks the release (already decided) and opens a revert pull request. The revert pull request is REASONED, NOT BUILT.
What GitHub Free private repos cannot enforce
| Thing | Free private | What we do instead |
|---|---|---|
| block a text conflict | works | this is why the laws turn clashes into conflicts |
| required CI before merge | no | the bot; CI on main |
| "only the bot merges" | no | a habit; CI on main catches a skip |
| stop a direct push to main | no | CI on main, revert |
| required review, code owners | no | the pull request author asks |
| signed commits required | no | dev shell signs; CI can only report |
| merge queue | no (Enterprise only) | the bot |
- Rules on a private Free repo: GitHub answered 403 "Upgrade to GitHub Pro". MEASURED on a private repo. Reviews, protected branches and code owners are paid on private repos: FROM DOCS (https://docs.github.com/en/get-started/learning-about-github/githubs-plans).
- GitHub Free now includes 12 US dollars a month of Actions use for private repos, not a number of minutes. FROM DOCS (same page).
- Not tested: the bot running as a GitHub Action (private repos in our test org cannot run Actions; the workflow is written and linted), and a GitHub App as the listed actor (tested with the repo admin role). Before use, the bot must also check that the pull request's own CI is green.
A clash the laws cannot stop, and the bot
Animation, 5 steps. Starts with: box pa "A: deletes a retired dependency"; box pb "B: starts using it"; box bot "merge bot"; cylinder mn "main". Connected: pa -> bot, pb -> bot, bot -> mn. Families, one colour each: pr "pull requests" (pa, pb); tool "our bot" (bot); main (mn). 1. Both pull requests are green on their own. Git sees no conflict. 2. The bot tests main plus A. Green, so it pushes A. pa -> bot: A 3. It pushes exactly what it tested. bot -> mn: tested 4. The bot tests the new main plus B. Red, so B goes back with the reason. pb -> bot: B 5. Main never saw the break.
1Both pull requests are green on their own. Git sees no conflict.
1 / 5
All steps (5)
the four breaks, given to the bot (real output, shortened)
$bun bot-proof.ts
3b retired dependency deleted, old PR starts using it
a merged, attempt 1 (163 ms)
b bounced: [deps] users uses cache.spare, not declared (132 ms)
main: green
8a two PRs each add half of a cycle
a merged, attempt 1 (170 ms)
b bounced: [cycle] billing -> users -> billing (151 ms)
main: green
$