The Steward, which merges and releases your repositories

What the Steward is#

The Steward looks after your repositories on GitHub. It keeps track of each repository's versions, merges your pull requests once they're ready, and releases each new version, but only in the repositories where you've said yes.

It does three jobs:

• It hands out versions. Before you, or your AI coding assistant, start work that will raise a repository's version, you ask the Steward for that version. Two pieces of work started side by side never get the same one. See Versions claimed up front.
• It merges your ready pull requests, in version order, once nothing holds them: tested on this PC first when GitHub runs no checks, caught up with their branch when that's all they wait for. See How the Steward merges pull requests.
• It releases new versions. When a repository's branch has a version with no release yet, the Steward makes the GitHub release, with the notes from your CHANGELOG.md. See How the Steward releases.

How it works#

It works in rounds. While it's on duty, and Merges and releases by itself is on in its settings, a round runs every 10 minutes. Each round:

1. Asks GitHub once about every repository it looks after: their open pull requests, their branches' heads and their releases.
2. Looks again only at the repositories with something new since the last round (and at all of them once an hour).
3. Merges each ready pull request in the repositories where merging is allowed.
4. Releases each new version in the repositories where releasing is allowed.
5. Raises an alarm for anything that needs you.

A quiet round is a single question to GitHub and no git at all. When a pull request waits only on something that settles by itself (its checks running, say), the next round comes 2 minutes later.

Code decides. No model is asked whether a pull request may merge or a release may go out: the Steward checks GitHub's own answers, your tests and the versions.

It acts as you. Merges, pushes and releases go through your own git and the GitHub CLI (gh), signed in as you.

Its home page#

The Steward's page is at http://steward.localhost:19494/, and Open on its card in Castellan goes there. From the top:

• Needs you: its alarms, each with Dismiss. See The Steward's alarms.
• Found on this PC: your repositories on GitHub that it could look after, with Look after. See Choosing what the Steward looks after.
• Your repositories: each one it looks after, with its checkout, its branch on GitHub, its latest release, and what it may do there.
• Merge conflicts: pull requests that conflicted with their branch in the last two weeks, and what the Steward did about each.
• Merge and release: Merge your ready PRs, Release and Refresh, for the repositories you tick. Each asks first.
• Last stage: what the last round or button did, repository by repository, with its log.
• Settings, in the title bar. See The Steward's settings and files.

Run now does a round at once, on duty or not.

What it never does#

• It never merges or releases without your yes. Each repository starts with merging and releasing off. Turn them on one repository at a time.
• It never touches your working tree. It fetches, and works in worktrees of its own in its work folder. Your checkout's files and branch stay as they are.
• It never force-pushes, and never deletes a branch of yours.
• It merges only what's ready: not a draft, merges cleanly, no failing or running checks, and a version of its own. Open a pull request that needs a review as a draft.
• It never merges anyone else's pull requests. Only yours, or your team's when you name one.
• It releases only to the repository's own GitHub repository.

What it needs#

• Git and the GitHub CLI, with gh signed in (gh auth login) as an account that can push to and merge in your repositories.
• A clone of each repository on this PC.
• Reeve, to find your repositories for you. Without Reeve, add them yourself in Castellan's Settings > Repositories.

Getting started#

1. Hire the Steward in Castellan: Settings > Developer agents. It's included in the Workshop license. See Hiring, switching and letting staff go.
2. Open its page, and pick the repositories it should look after under Found on this PC: Choosing what the Steward looks after.
3. For each one, decide whether it merges your ready pull requests, and whether it releases: both start off.
4. Once you trust it, turn on Merges and releases by itself in its settings, so its rounds do it for you.
5. Tell your AI coding assistant to claim a version before it starts, and to vouch for its branch once it's pushed: Vouching, and pull requests the Steward opens.