merge-steward

library0.30.3jsnpmunverified

Self-hosted serial merge queue for GitHub that validates PRs cumulatively against the exact future main branch. Version 0.30.3 requires Node.js 24+. It builds speculative branches (main + A, main + A + B, etc.), runs CI on those, and fast-forwards green sequences to main — catching integration bugs before merge. Unlike GitHub's merge queue or linear-merge, it never pauses for main's CI and never merges unvalidated combinations. Communicates solely through GitHub (PRs, checks, labels, branches), supports retry-on-failure with incident records, and pairs with review-quill without dependency. Designed for bot-managed or human-managed repos.

devops

npm install merge-steward

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MERGE-STEWARD

merge-steward

devopsjavascriptv0.30.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

command

✓ import { execSync } from 'node:child_process'; execSync('merge-steward queue status --repo repo')

✗ const mergeSteward = require('merge-steward')

merge-steward is a CLI tool, not a library. Use child_process to invoke it. No programmatic API is exported.

config

✓ merge-steward init https://queue.example.com

✗ merge-steward init --url https://queue.example.com

The URL is a positional argument, not a flag. Do not use --url.

type imports

✓ // No TypeScript types are published. Use the CLI directly.

✗ import { QueueStatus } from 'merge-steward'

merge-steward does not ship TypeScript definitions. All interaction is via CLI.

Install globally, initialize a queue server, attach a repository, run diagnostics, check service and queue status.

pnpm add -g merge-steward merge-steward init https://queue.example.com merge-steward repo attach owner/repo --base-branch main merge-steward doctor --repo repo merge-steward service status merge-steward queue status --repo repo

Debug

Known issues

breakingRequires Node.js >=24.0.0. Does not work on older Node.js versions.

fix

Upgrade Node.js to at least 24.0.0.

affects: <24.0.0

deprecatedCommands 'merge-steward pr status' and 'merge-steward queue reconcile' were undocumented before v0.28 but are now stable. No changes expected.

fix

No action needed. These commands are stable.

affects: >=0.28

gotchaThe webhook URL is printed only once during 'init'. If lost, you must re-run 'init' and reconfigure GitHub App webhook settings.

fix

Store the webhook URL securely after init. To recover, run 'merge-steward init' again and update GitHub App settings.

affects: >=0.1

gotchaThe steward learns required checks from GitHub branch protection at runtime — it does not cache them. If branch protection changes while the queue is running, it can take up to the reconcile interval (5 min) to pick up new checks.

fix

Force reconcile with 'merge-steward queue reconcile --repo <id>' or wait up to 5 minutes.

affects: >=0.1

gotchaThe queue does not prevent concurrent pushes to main outside of the steward. If someone manually pushes to main, the steward's speculative branches may become stale and need retriggering.

fix

Use branch protection to restrict direct pushes to main, and ensure only the steward's token has push access.

affects: >=0.1

Errors

Common errors & fixes

Error: Failed to initialize queue: Webhook URL already exists

Running 'merge-steward init' on a directory that already has config files.

fix

Use 'merge-steward init --force' to overwrite, or run init in a clean directory.

Error: repo attach failed: Repository not found

The GitHub App is not installed on the target repo, or the token lacks permissions.

fix

Ensure the GitHub App is installed on owner/repo and the token has 'Contents: write', 'Pull requests: write', and 'Checks: read & write'.

Error: Doctor check failed: gh not found in PATH

The GitHub CLI (gh) is not installed or not in PATH.

fix

Install gh from https://cli.github.com and ensure it's in PATH.

Error: Service logs failed: Systemd unit not found

The systemd unit was not written because --no-systemd was passed to init, or systemd is not available.

fix

Run 'merge-steward init' without --no-systemd, or manually configure the service.

Upgrade

Version history

0.30.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/krasnoperov/patchrelay ↗

packagemerge-steward ↗

homepagehttps://github.com/krasnoperov/patchrelay/tree/main/packages/merge-steward#readme ↗