Home / Blog / Cost and billing
GitHub merge queue: setup, merge_group and the Actions minutes it adds
How to turn on GitHub's merge queue, what the merge_group event runs, and what it adds to your Actions bill, counted on real pull requests. Workflow and ruleset adapted from ours.
GitHub’s merge queue works on a public repository owned by an organisation, and it runs each required workflow a second time for every pull request, in a merge group. In 58 pull requests that we queued with no failure, every one ran exactly twice, once on the pull request and once in the queue, which doubled the job-minutes. A pull request that failed once combined cost two of the pull requests behind it an extra run. Our GitHub Actions cost guide has the rates.
- A merge queue is available in any public repository owned by an organisation; we ran one in a public repository in an organisation.
- The workflow must trigger on merge_group. In our test, without it each pull request was removed from the queue when the check timed out, and stayed open.
- In 58 queued pull requests with no failure, each ran its workflow once on the pull request and once in its merge group.
- With build concurrency 1 the queue merged about one pull request every 75 seconds; with 5 and groups of up to 5, five merged together.
- A pull request that failed once combined was removed and the two behind it ran again: 8 merge-group runs for 6 pull requests.
- Skipping the job on pull_request with an if: condition satisfied the required check and halved the minutes: 9 of 9 merged, one job-minute each.
GitHub’s pages on the merge queue explain how to turn it on and say nothing about what it costs in Actions minutes or how loaded the runners get, and they give no default for the status check timeout or the wait to fill a group. We turned one on in a public repository, put pull requests through it, and counted. Below is the setup that worked, a complete workflow, and the minutes.
Does a merge queue work on a public repository?
Yes, if the repository belongs to an organisation. GitHub’s page says merge queues are available in any public repository owned by an organisation, and in private repositories only when the organisation is on GitHub Enterprise Cloud. A repository owned by a personal account is not covered. We used a public repository in an organisation, and the queue worked as the documentation describes. One restriction is easy to miss: a branch protection rule with a wildcard in its branch pattern cannot have a merge queue, so name the branch.
Set it up
There are two parts, and the second is the one people forget. The repository needs a rule that requires a merge queue, and every workflow that reports a required check needs to run for the queue’s merge groups. The rule is in the repository’s branch settings, as “Require merge queue”, or in a ruleset. This is the ruleset we used, with the branch name changed to main, created with the REST API, for a branch that requires one check called check.
{
"name": "main-queue",
"target": "branch",
"enforcement": "active",
"conditions": { "ref_name": { "include": ["refs/heads/main"], "exclude": [] } },
"rules": [
{
"type": "merge_queue",
"parameters": {
"check_response_timeout_minutes": 15,
"grouping_strategy": "ALLGREEN",
"max_entries_to_build": 5,
"max_entries_to_merge": 5,
"merge_method": "MERGE",
"min_entries_to_merge": 1,
"min_entries_to_merge_wait_minutes": 5
}
},
{
"type": "required_status_checks",
"parameters": {
"strict_required_status_checks_policy": false,
"do_not_enforce_on_create": false,
"required_status_checks": [{ "context": "check" }]
}
}
]
}
gh api repos/OWNER/REPO/rulesets --input ruleset.json
The fields are GitHub’s. max_entries_to_build is the build concurrency, how many queued pull requests may have checks running at once. max_entries_to_merge and min_entries_to_merge are the group size limits, and min_entries_to_merge_wait_minutes is how long the queue waits for the minimum to be reached before it merges a smaller group. ALLGREEN means every pull request’s own merge commit must pass its required checks before the group merges; HEADGREEN asks only that the head of the group does.
The workflow must run on merge_group
A merge queue tests each pull request in a temporary branch that GitHub creates, and it starts the required checks by sending a merge_group event. If a workflow does not listen for it, the required check is never reported, and the pull request is removed from the queue when the status check timeout passes. The event is separate from pull_request and push. Its only activity type is checks_requested. This is a complete workflow, adapted from the one we ran by putting a test script where ours had a 30-second sleep, with the action pinned to a commit.
name: ci
on:
pull_request:
merge_group:
permissions:
contents: read
jobs:
check:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- run: ./run-tests.sh
The job name, check, is what the ruleset requires, so it is the same on both events. In the merge group the commit being tested is the temporary branch, with the pull request merged into the latest base and into every pull request ahead of it in the queue. That is the point of the queue, and it is also why the checks must run again.
What the queue runs, and what it costs
GitHub’s page describes a temporary branch for each queued pull request, holding the pull request on top of the base and of every pull request ahead of it, and a merge_group event for each. The count is therefore one extra run of every required workflow per pull request. We checked it. In all 58 pull requests of the first two configurations below, the pull request had one run on pull_request and one in its merge group, and nothing more, in both of the group sizes we tried. Group size decided when pull requests merged, not how many runs the queue started.
| Queue settings | Pull requests | Pull-request runs | Merge-group runs | Job-minutes | Seconds to merge a queue of pull requests |
|---|---|---|---|---|---|
| Build concurrency 1, groups of 1 | 40 | 40 | 40 | 80 | 612 to 630, for 8 |
| Build concurrency 5, groups of up to 5 | 18 | 18 | 18 | 36 | 164 to 171, for 6 |
| As above, the third pull request fails once combined | 18 | 18 | 24 | 42 | 162 to 166, for 6 (5 merged) |
The 30-second job was billed as a whole minute each time, so a pull request cost 2 job-minutes, 1 on the pull request and 1 in the queue. We would expect a longer job to scale the minutes and leave the run counts alone, but we ran only this one. The last column is the time from the first pull request being queued to the last one merging, for a queue of 8 in the first row and 6 in the others, as the range over the queues.
Build concurrency 1 serialises the queue. Each pull request waits for the one before it to merge, and the pull requests merged about 75 seconds apart: the first after a median of 92 seconds, the fourth after 315, the eighth after 617. With build concurrency 5 and groups of up to 5, the first five pull requests of a queue merged together after a median of 82 to 88 seconds, and the sixth, which had to wait for a second group, after 161. More build concurrency merges sooner, and it also puts more runs on your runners at once, which is where the account’s cap on concurrent jobs comes in.
To price it for your own repository, count the minutes of one run of the required workflow, the pull-request runs each pull request gets, and how often a queue entry has to be built again. For a private repository the number of extra minutes a day is the pull requests you merge, times the minutes of one run, times 1 plus the re-runs per pull request. Forty pull requests a day, a 10-minute workflow, and no failures: 400 minutes a day on pull_request alone, and 800 with the queue. At the $0.006 a minute GitHub lists for a 2-core Linux runner that is $2.40 a day more, before the included amount of your plan. In a public repository none of it is billed on standard runners, and the only cost is time. Our pricing post has GitHub’s rates and allowances in full, and the calculator turns a month of minutes into a bill. Our per-minute rate for every size, beside GitHub’s, is on the GitHub Actions runner pricing page.
When a pull request fails in the queue
The failure case is the one the queue exists for, and it is where the extra minutes come from. In the third configuration of our test the third pull request of each queue carried a file that makes only the merge-group run fail: green on its own, red once combined. In all three queues the third pull request was removed from the queue and stayed open. The fourth and fifth had been built on top of it, so each ran twice, the first time failing because of the pull request it contained, and the second time passing once the queue had rebuilt it without it. The sixth had not started building, and ran once. The five good pull requests merged, the last three after a median of 156 to 159 seconds instead of 82 to 88.
So a failure costs more than the failing run: 8 merge-group runs and 14 job-minutes for the queue of six, against 6 and 12 with no failure. The pull requests re-run were the ones being built behind the failing one at that moment. We think that is why the sixth escaped, as build concurrency was 5 and the failure was third, but we tested only that setting and did not test the reason. If your checks fail often, a lower build concurrency is worth trying, because a higher number merges sooner when everything passes and may re-run more when something does not.
Running the suite twice
The cost above is the price of testing the combined result, and the part that can be trimmed is the pull-request run. GitHub’s troubleshooting page says a job skipped by a conditional reports success, so a required check can be satisfied on the pull request by a job that does not run, with the full suite left to the merge group. We measured it: the check job carried if: github.event_name == 'merge_group', and nine pull requests went through three queues. All nine merged, 86 to 95 seconds after being queued. Each pull-request run concluded skipped, satisfied the required check and billed nothing, and each merge-group run billed one minute. That is one job-minute a pull request instead of two.
The trade is that nothing runs before the queue. A change that fails is found in the merge group, where a failure costs the rebuilds above, and the author learns about it later. A cheap job on the pull request, such as lint, with the long suite only in the merge group, is the middle ground. Try it on a branch before you rely on it.
The one thing the workflow cannot do is leave out the merge_group trigger. We ran that too. No merge-group run started, so the required check never reported on the merge group. Each pull request sat in the queue until the ruleset’s check timeout, five minutes in our test, and was then removed with the reason checks_timed_out. It stayed open, with its own pull-request check green. If a pull request leaves your queue after exactly that timeout, look for the trigger first.
Jumping the queue
When you add a pull request you can ask for it to go to the top of the queue. GitHub’s page warns that this causes a full rebuild of every pull request already being built, because the reordering breaks the commit graph that their merge groups were built on. We did not run it, but we would expect the cost of the failure case above: the entries already being built run their checks again. Treat it as something to do rarely. If you also run a concurrency group on the pull request workflow, our post on what five pushes do under each concurrency setting covers what a new push does to the run that is still going.
What we ran
All of it ran on 17 November 2026 on GitHub-hosted ubuntu-24.04 runners, in a public repository in an organisation, where standard runners are free. The rulesets, the workflow, the script that opens and queues pull requests, the method and every row are in the B2 directory of runners-io/ci-measurements. The check is a 30-second job. A real suite runs for longer, which makes every figure of minutes larger and makes no difference to the counts of runs. For the cap on how many jobs run at once, which a queue with a high build concurrency can reach, see the limits table, and for how a run waits when no runner is free, the guide to why jobs wait for a runner.
Sources
- Managing a merge queue (docs.github.com)
- REST API endpoints for rules (docs.github.com)
- Events that trigger workflows (docs.github.com)
- Actions runner pricing (docs.github.com)
- GitHub Actions billing (docs.github.com)
- Troubleshooting required status checks (docs.github.com)
- actions/checkout tag v7.0.1 (GitHub API) (api.github.com)
- B2: a merge queue and its minutes (runners-io/ci-measurements) (github.com)
Frequently asked questions
Does GitHub merge queue work on a public repository?
Yes, if an organisation owns it. GitHub's page says merge queues are available in any public repository owned by an organisation, and in private ones only on GitHub Enterprise Cloud. We ran one in a public repository in an organisation and it worked as documented.
What does the merge_group event do?
It starts your workflows when a pull request enters the merge queue, on a temporary branch holding the pull request and those ahead of it. Without a merge_group trigger the required check is never reported: in our test each pull request left the queue as checks_timed_out at the ruleset's timeout and stayed open. Its only activity type is checks_requested.
Does a merge queue use more GitHub Actions minutes?
Yes: one extra run of each required workflow per pull request. In our test a 30-second check cost 2 job-minutes: one run on pull_request, one in its merge group. A failure re-runs those behind it. Skipping the job on pull_request with if: github.event_name == 'merge_group' brought it to 1, because a skipped job reports success.
What happens when a pull request fails in the merge queue?
GitHub removes it and rebuilds the entries behind it without it. In our test the third of six pull requests failed, the fourth and fifth ran twice, and the other five merged, the last three about 70 seconds later than when nothing failed.