merge-steward 0.30.1 → 0.30.2
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 +15 -11
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,9 +1,11 @@
|
|
|
1
1
|
# merge-steward
|
|
2
2
|
|
|
3
|
-
Self-hosted serial merge queue for bot-managed and human-managed GitHub pull requests. Admits approved PRs whose required checks are green, builds speculative branches on top of the latest `main`, waits for CI on those integrated SHAs, and fast-forwards `main` to the tested result.
|
|
3
|
+
Self-hosted serial speculative merge queue for bot-managed and human-managed GitHub pull requests. Admits approved PRs whose required checks are green, builds speculative branches on top of the latest `main`, waits for CI on those integrated SHAs, and fast-forwards `main` to the tested result.
|
|
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: a self-hosted merge queue without the Enterprise gate](https://blog.krasnoperov.me/posts/merge-steward).
|
|
8
|
+
|
|
7
9
|
## Why this matters
|
|
8
10
|
|
|
9
11
|
PRs delivered through the queue are tested against `main` as it was at admission time, and re-validated if `main` advances during validation. No more "CI was green yesterday, breaks on merge today" — the queue catches the integration bug before `main` ever sees it.
|
|
@@ -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: a self-hosted merge queue without the Enterprise gate](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
|