What the agent does
The agent starts by reading every workflow, because a merge queue only works when each required check runs for the queue's temporary branch and not only for the pull request. In a repository like miniflux/v2 there are nine under .github/workflows. tests.yml runs on pull_request to main and workflow_dispatch: a Unit Tests job with a matrix over ubuntu-latest, windows-latest and macOS-latest that runs make test (go test -cover -race -count=1 ./...) on Ubuntu and go test ./... elsewhere, and an Integration Tests job with a postgres:11 service that runs make integration-test. linters.yml has the same triggers with three jobs: Javascript Linter (jshint 2.13.6 and ESLint 8.57.0 over internal/ui/static/js), Golang Linters (golangci-lint-action and gofmt -d -e .) and Commit Linter, which already carries if: github.event_name == 'pull_request' and runs scripts/commit-checker.py with github.event.pull_request.base.sha and head.sha. The rest are release and packaging work: build_binaries.yml, docker.yml, debian_packages.yml and rpm_packages.yml run on tags, schedules and pull requests filtered by paths, codeql-analysis.yml runs on push and pull_request with paths on **.go and **.js, and codeberg_mirror.yml and stale.yml have nothing to do with checks. Every action is pinned to a commit with a version comment, and the workflows set permissions: read-all.
The agent then sorts the jobs into the ones a queue should require and the ones it must not. Unit Tests and Integration Tests and the two lint jobs run on every pull request regardless of files changed, so they are the natural required checks; the agent adds merge_group with types: [checks_requested] to the on block of tests.yml and linters.yml, keeping pull_request and workflow_dispatch as they are. Commit Linter is left alone because its if already skips the queue event and its inputs do not exist there, which the pull request explains. The path-filtered workflows are the trap: merge_group ignores paths and paths-ignore, so adding it to build_binaries.yml would build every queued change, and making a path-filtered job a required check would stall every pull request that does not touch those paths. The agent leaves those four workflows unchanged and says in the pull request why they should stay optional.
Two smaller things make the queue behave. The agent adds a concurrency block to tests.yml and linters.yml keyed on ${{ github.workflow }}-${{ github.ref }} with cancel-in-progress: true; a queue entry has its own ref under refs/heads/gh-readonly-queue/main/, so queued entries never cancel each other while a new push to a pull request still cancels its stale run. And it checks the if conditions that reference github.repository_owner, which still hold under merge_group, and the go-version: stable setup, which needs no change. CodeQL keeps running on push to main, which is where the queue's merges land.
The agent proves the YAML before asking anyone to require anything. It runs actionlint over every changed workflow, and because the sandbox has no GitHub event to replay, it runs act -n -e with a merge_group event payload against tests.yml and linters.yml to list which jobs would be selected for the queue event and which would be skipped. It also runs make test once in the sandbox to confirm the suite it is about to make a required check is green on the current tree. The pull request lists the exact check names the branch rule should require, as GitHub renders them: Unit Tests (ubuntu-latest), Unit Tests (windows-latest), Unit Tests (macOS-latest), Integration Tests, Javascript Linter and Golang Linters.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Make this repository's CI work with a GitHub merge queue. Read every file under .github/workflows and the Makefile first. Add the merge_group trigger with types checks_requested to the workflows whose jobs run on every pull request and should become required checks, keep their existing triggers, and leave any job that reads github.event.pull_request guarded so it skips the queue event. Do not add merge_group to workflows that use paths filters, and explain in the pull request why those must not be required checks. Add a concurrency group keyed on workflow and ref with cancel-in-progress to the workflows you changed. Run actionlint on every changed file, use act with a merge_group event payload to list which jobs the queue would run, run the unit tests once, and open a pull request that names the exact check names to require in the branch rule and the one setting to enable the queue.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that changes only tests.yml and linters.yml: a merge_group trigger, a concurrency block and nothing else. The description has a table of every workflow in the repository with its triggers and the decision for each, the list of check names to require, and the sentence on enabling the merge queue in the branch rule for main that only a repository admin can do.
The run's record keeps the actionlint output, the act dry run showing the jobs selected for a merge_group event and Commit Linter skipped, and the make test run on the current tree, so a reviewer knows the checks they are about to require pass today.
Before merging, a reviewer turns on the merge queue for main, sets the required checks to the names in the description, and watches the first queued pull request go through. If any optional workflow should become required later, the path filter is the thing to remove first.
Run it on every repository moving to a merge queue
A maintainer hands this off from the terminal: one POST /o/{org}/sessions with this body and the repository in resources. An organisation enabling queues across many repositories sends one request per repository, each with a request_id that is a UUID v5 of the repository path so a retry returns the run it already started, and the key's webhook_url reports each finished run with its pull request.
Each run reads that repository's own workflows and makes its own table, because the right answer depends on which jobs use path filters and which read pull request fields.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The mistakes that break a merge queue are quiet ones: a required check that never runs for the queue event, a path-filtered job that stalls every unrelated pull request, a job that reads github.event.pull_request and fails on a payload that has no such field. The agent reads every workflow in its own sandbox, decides each one with a reason, and replays a queue event with act before anyone changes a branch rule.
The deliverable is a small diff plus a decision table, and the record behind it shows every command. That is what a reviewer needs to enable a setting that gates every future merge.
Frequently asked questions
Why not add merge_group to every workflow?
Because merge_group ignores paths filters, so the packaging and binary workflows would run for every queued change, and a required check that is sometimes skipped by a path filter blocks the queue. The pull request keeps those workflows optional and explains the rule.
What happens to the commit message check in the queue?
It is skipped, on purpose. The job already has if: github.event_name == 'pull_request', and it reads github.event.pull_request.base.sha, which a merge_group payload does not carry. Commit messages are checked on the pull request, before it enters the queue.
Which names go in the required checks list?
The job names as GitHub renders them, including the matrix value for matrix jobs: Unit Tests (ubuntu-latest) rather than unit-tests. The pull request lists each one so the branch rule can be filled in without guessing.
Will the concurrency group cancel queued runs?
No. Each queue entry runs on its own temporary ref, so the group key workflow-ref is different for every entry. A new push to a pull request still cancels that pull request's stale run, which is what the group is for.
Does the agent enable the queue itself?
No. Branch rules are repository settings that need an admin, and the agent has only the repository's contents. It prepares the workflows, proves them with actionlint and act, and tells the admin exactly what to set.
More GitHub Actions jobs
More jobs like this: Hand off a long task
- Add Mermaid Diagrams to a Docusaurus Site (Docusaurus)
- Add Mermaid Diagrams to an Eleventy Blog (Eleventy)
- Add Mermaid Diagrams to a Hugo Docsy Site (Hugo)