# Make GitHub Actions Workflows Run in a Merge Queue

Yes. An agent adds the merge_group trigger to the workflows that should be required checks, keeps pull-request-only jobs guarded and opens a PR naming the checks.

[Run this on Rush](https://cloud.getrush.ai/run/add-merge-queue-support/github-actions/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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

- [Add OpenSSF Scorecard to a Repository with GitHub Actions](https://getrush.ai/run/add-openssf-scorecard/github-actions/)
- [Add a Release Workflow to a Custom GitHub Action](https://getrush.ai/run/add-release-workflow/github-actions/)
- [Post Slack Alerts When GitHub Actions Workflows Fail](https://getrush.ai/run/add-slack-failure-alerts/github-actions/)

## More jobs like this: Hand off a long task

- [Add Mermaid Diagrams to a Docusaurus Site](https://getrush.ai/run/add-mermaid-diagrams/docusaurus/)
- [Add Mermaid Diagrams to an Eleventy Blog](https://getrush.ai/run/add-mermaid-diagrams/eleventy/)
- [Add Mermaid Diagrams to a Hugo Docsy Site](https://getrush.ai/run/add-mermaid-diagrams/hugo/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
