Files
PaperClipAI/doc
DottaandClaude Fable 5.2 6826800425 feat(ci): report the required checks on merge-queue commits (#21545)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Each merge to `master` publishes the standard image, and the time
from merge to published image limits how fast a fix reaches users
> - #21096 lets `docker.yml` push an image that the merge queue already
built, but the merge queue is not on
> - The `master` ruleset requires `ci / verify` and `ci / e2e`. Only
`pr.yml` reports them, and only for pull requests
> - A merge queue waits for the same two names on its merge-group
commit. No workflow reports them there, so every queued merge would
stall
> - This pull request adds a workflow that reports both names on
merge-group commits
> - The benefit is that the owner can turn the merge queue on with one
ruleset change

## Linked Issues or Issue Description

Refs #21096

**What existing behavior does this improve?**

The merge-queue image build from #21096. It cannot run until the merge
queue is on, and the merge queue cannot be turned on safely.

**Current behavior**

`ci / verify` and `ci / e2e` come from `pr.yml`, which runs on
`pull_request` only. With a merge queue, GitHub waits for both checks on
the merge-group commit. They never arrive. Each queued pull request
would time out and leave the queue.

**Proposed behavior**

`merge-queue-checks.yml` runs on `merge_group` and reports `ci / verify`
and `ci / e2e`. It runs no tests. It does not check out the queued
commit. It has no token permissions and no secrets.

**Reason and benefit**

A pull request enters the queue only after both checks pass on the pull
request. A queued merge therefore has the same protection as a direct
merge today. The exact-source gate still tests each `master` commit
before publication. Real tests on the combined tree can replace these
jobs later under the same names.

## What Changed

- Added `.github/workflows/merge-queue-checks.yml`. It reports `ci /
verify` and `ci / e2e` on merge-group commits.
- Added `scripts/__tests__/merge-queue-checks-workflow.test.mjs`. It
fails if the names differ from the names that `pr.yml` reports, or if
the workflow gains a checkout, an action, a secret, a token permission
or a self-hosted runner.
- `pr-trusted.yml` now runs that test and
`scripts/merge-group-image.test.mjs` in a step that skips test files an
older checkout does not have. The second test came with #21096 but no CI
step ran it.
- `scripts/merge-group-image.mjs find` now waits up to 15 minutes for a
merge-queue image build that is still queued or running. The queue can
land a commit before its image build ends. Without the wait, the
`master` push always builds from source.
- `doc/RELEASING.md` explains the workflow and lists the ruleset
settings that turn the queue on and off.

## Verification

- `node --test scripts/__tests__/merge-queue-checks-workflow.test.mjs`:
2 pass.
- `node --test scripts/merge-group-image.test.mjs`: 10 pass, with new
cases for unfinished builds.
- `node --test scripts/__tests__/release-verify-workflow.test.mjs`:
pass.
- `actionlint` on both changed workflows: no findings.
- Not verified: no `merge_group` event can fire before the queue is on.
The first queued merge is the live test. `pr.yml` calls
`pr-trusted.yml@master`, so the new CI step runs only after this merges.

Owner steps after merge:

1. In the `master` ruleset, add **Require merge queue**: Squash, build
concurrency 5, group size 1 to 5, status check timeout 60 minutes.
2. After the first queued merge, confirm that the `master` commit SHA
equals the SHA of its merge-group runs.

## Risks

- Low risk while the queue is off. The workflow has no trigger other
than `merge_group`.
- With the queue on, the queue does not test the combined tree. Two pull
requests that pass alone can still break `master` together. This is the
same as today.
- A merge-queue image build that hangs delays the source build by up to
15 minutes. A build that fails does not.
- If GitHub does not accept a job named `ci / verify` for the required
context, queued merges time out. Rollback: remove the merge queue rule.

## Model Used

- Claude Fable 5.2 (`claude-fable-5-2`), Claude Code, with tool use and
code execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-13 21:18:13 -06:00
..
…
…
…
…