merge-steward 0.30.1 → 0.30.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -12
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
# merge-steward
|
|
2
2
|
|
|
3
|
-
Self-hosted
|
|
3
|
+
Self-hosted merge queue for bot-managed and human-managed GitHub pull requests. Merge Steward turns reviewed PRs into a tested landing train: it runs CI on the exact future `main` SHAs, validates several PRs in parallel, and fast-forwards through the green sequence as soon as it is safe.
|
|
4
4
|
|
|
5
5
|
Independent of PatchRelay. Communicates through GitHub only — PRs, reviews, checks, labels, branches. Pairs with `review-quill`; neither requires the other.
|
|
6
6
|
|
|
7
|
+
For the background story and design trade-offs, read [merge-steward: speculative integration, parallel validation, fast-forward landing](https://blog.krasnoperov.me/posts/merge-steward).
|
|
8
|
+
|
|
7
9
|
## Why this matters
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
The queue keeps delivery fast without pretending branch CI is enough. Each speculative branch is the cumulative queue order on top of the latest base: `main + A`, then `main + A + B`, then `main + A + B + C`. No more "CI was green yesterday, breaks on merge today" — the integration bug is caught before `main` ever sees it.
|
|
10
12
|
|
|
11
13
|
## How it works
|
|
12
14
|
|
|
@@ -36,17 +38,18 @@ Prerequisites: Node.js 24+, `gh` CLI in `PATH`, `git`.
|
|
|
36
38
|
```bash
|
|
37
39
|
pnpm add -g merge-steward
|
|
38
40
|
merge-steward init https://queue.example.com
|
|
39
|
-
merge-steward attach owner/repo --base-branch main
|
|
41
|
+
merge-steward repo attach owner/repo --base-branch main
|
|
40
42
|
merge-steward doctor --repo repo
|
|
41
43
|
merge-steward service status
|
|
42
44
|
merge-steward queue status --repo repo
|
|
43
45
|
```
|
|
44
46
|
|
|
45
|
-
- `init` writes config files
|
|
46
|
-
- `
|
|
47
|
+
- `init` writes config files and a systemd unit, then prints the webhook URL to configure in GitHub.
|
|
48
|
+
- You still need to install `merge-steward-webhook-secret` and `merge-steward-github-app-pem` via systemd credentials, or provide the documented environment/file fallbacks.
|
|
49
|
+
- `repo attach` discovers the default branch from GitHub and stores a per-repo config.
|
|
47
50
|
- Required checks are learned from GitHub branch protection at runtime — the steward does not keep a local copy.
|
|
48
51
|
|
|
49
|
-
Full setup (GitHub App permissions, secrets, webhook events, systemd, HTTP API): [docs/merge-steward.md](
|
|
52
|
+
Full setup (GitHub App permissions, secrets, webhook events, systemd, HTTP API): [docs/merge-steward.md](https://github.com/krasnoperov/patchrelay/blob/main/docs/merge-steward.md).
|
|
50
53
|
|
|
51
54
|
## Everyday commands
|
|
52
55
|
|
|
@@ -77,7 +80,7 @@ The real gate is:
|
|
|
77
80
|
- configured required checks are green
|
|
78
81
|
- the steward's speculative integrated branch also passes CI
|
|
79
82
|
|
|
80
|
-
`review-quill/verdict` only matters if you include it in the repo's required checks. Branch protection is useful as defense in depth, but the steward merges by fast-forwarding `main` to the already-tested speculative SHA — not by pressing GitHub's merge button. Successful merges therefore depend on the steward App being allowed to push to the protected branch. See [docs/merge-steward.md](
|
|
83
|
+
`review-quill/verdict` only matters if you include it in the repo's required checks. Branch protection is useful as defense in depth, but the steward merges by fast-forwarding `main` to the already-tested speculative SHA — not by pressing GitHub's merge button. Successful merges therefore depend on the steward App being allowed to push to the protected branch. See [docs/merge-steward.md](https://github.com/krasnoperov/patchrelay/blob/main/docs/merge-steward.md) for the full App permission set.
|
|
81
84
|
|
|
82
85
|
**`main`'s own CI is information-only.** The speculative SHA the steward tests *is* the exact tree that becomes `main`, so re-testing `main` after the push adds no signal — it only catches flakiness or out-of-band changes (direct pushes, hotfixes). The queue therefore **ignores `main`'s CI entirely** for advancement: it does not gate landing on `main` being green, does not wait for `main` CI before the next landing, and is never "paused" by a red `main`. A red `main` with a green speculative SHA simply means the red was flaky or is fixed by landing — so the steward lands. Use `main`'s CI as a project-health canary, not a queue control.
|
|
83
86
|
|
|
@@ -94,8 +97,9 @@ Neither service calls the other's API.
|
|
|
94
97
|
|
|
95
98
|
## Reference
|
|
96
99
|
|
|
97
|
-
- [
|
|
98
|
-
- [docs/merge-
|
|
99
|
-
- [docs/
|
|
100
|
-
- [docs/
|
|
101
|
-
- [
|
|
100
|
+
- [merge-steward: speculative integration, parallel validation, fast-forward landing](https://blog.krasnoperov.me/posts/merge-steward) — background essay and design trade-offs
|
|
101
|
+
- [docs/merge-steward.md](https://github.com/krasnoperov/patchrelay/blob/main/docs/merge-steward.md) — operator reference: GitHub App permissions, secrets, webhook, repo config, full CLI, HTTP API, queue state machine, systemd, troubleshooting
|
|
102
|
+
- [docs/merge-queue.md](https://github.com/krasnoperov/patchrelay/blob/main/docs/merge-queue.md) — the two-service delivery story
|
|
103
|
+
- [docs/github-queue-contract.md](https://github.com/krasnoperov/patchrelay/blob/main/docs/github-queue-contract.md) — shared GitHub artifacts
|
|
104
|
+
- [docs/design-docs/merge-steward.md](https://github.com/krasnoperov/patchrelay/blob/main/docs/design-docs/merge-steward.md) — design rationale
|
|
105
|
+
- [README.md](https://github.com/krasnoperov/patchrelay/blob/main/README.md) — the three-service stack overview
|