---
title: "Merging without a queue"
description: How main stays green with no merge queue.
source: merge.dh.md
---
<!-- Made by dh llm from the source; nobody edits this file. -->

# 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
1. **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.
2. **A claim is a git conflict.** Whatever two pull requests could both claim is a path or one line in a sorted list. `context.yaml` holds a random id. GitHub refuses to merge a text conflict, on any plan.
3. **No file every pull request edits.** The kernel finds contexts; shared lists are generated and not committed.
4. **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.yaml` alone 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)
1. You label a pull request `merge`.
2. The bot joins it with the newest main.
3. It runs the fast whole-repo check (names, needs, uses, generated files; add the compile step per language).
4. It pushes exactly what it tested. If main moved meanwhile, it starts again.
5. 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.

```terminal
$ 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
```
