A concurrency group lets one run work and, by default, one wait, and a newer run replaces the one that is waiting. We pushed five commits in about 43 seconds to a branch, on ten branches at once. With a group, runs 2, 3 and 4 were cancelled while they waited and only runs 1 and 5 ran. Adding cancel-in-progress cut the runs that were working as well. queue: max ran all five, in order. Our GitHub Actions queue guide explains why jobs wait.
- A concurrency group lets one run work and one wait, and a newer run replaces the one that is waiting.
- Under a group alone, runs 2, 3 and 4 of five pushes were cancelled while pending, and only runs 1 and 5 ran.
- cancel-in-progress also cut the runs that were working: only the last of five finished.
- queue: max ran all five runs one at a time, in push order, in 299 seconds against about 105 with no group.
- github.head_ref is empty on a push, so a group keyed on it with a run-id fallback never cancels anything.
- In a matrix, a job-level group that does not name the leg made the legs cancel each other: 70 of 75 jobs were cancelled.
GitHub’s documentation says what each option means and is silent on what you will see. This post puts the two side by side: what the documentation says each setting does, and what five real pushes did under it, on GitHub-hosted runners, with the workflow and the raw rows public. It also covers the two settings that most often surprise people, a group inside a matrix and a group keyed on github.head_ref. If a run is stuck pending rather than running, the guide to queued, pending and waiting runs tells that wait apart from the others.
What a concurrency group does
A group is a string. At most one run or job in a group works at a time. When another is started while one is working, it is pending. By default only one run can be pending, so when a third arrives it replaces the second, which is cancelled. Two options change that. cancel-in-progress: true also cancels the run that is working, so the newest run always wins. queue: max, which GitHub announced on 7 May 2026, lets up to 100 runs wait instead of one, and runs them first in, first out, though GitHub adds that ordering is not guaranteed. The two cannot be combined, and GitHub says the pair is a validation error. The group name is not case sensitive.
The key can go in two places. At the top of a workflow, it can read only the github, inputs and vars contexts. On a job, it can also read needs, strategy and matrix. That difference matters in a matrix, below.
What five pushes did
Every workflow here runs one job that sleeps for 40 seconds on ubuntu-24.04. For each setting we pushed five commits to one branch, one after another, about 9 seconds apart, and did that on ten branches at once (five for the last settings in the table). The table is what happened to the five runs of a branch. Every repetition of a setting gave the same pattern, so there is no spread to print for the pattern, only for the times.
| Setting | Runs that finished | Runs cancelled | Job-minutes in a private repository | Seconds, first push to last job done |
|---|---|---|---|---|
| No concurrency key | All five | None | 5 | 105 (95 to 109) |
| A group, nothing else | Runs 1 and 5 | 2, 3 and 4, before any job started | 2 | 106 (101 to 110) |
| A group with cancel-in-progress: true | Run 5 only | 1, 3 and 4 while running, 2 before it started | 4 (3 to 4) | 118 (102 to 127) |
| A group with queue: max | All five, one at a time, in push order | None | 5 | 299 (281 to 311) |
| github.head_ref || github.run_id with cancel-in-progress: true, on a push | All five | None | 5 | 91 (90 to 92) |
| A three-leg matrix, a job-level group that does not name the leg, cancel-in-progress: true | One leg of run 5 on each branch | Every other job | 13 (9 to 16) | 107 (95 to 385) |
| The same matrix, the group names the leg | All three legs of run 5 | All three legs of runs 1 to 4, while running | 15 (15 to 19) | 105 (98 to 384) |
| queue: max with cancel-in-progress: true | None: GitHub refused the workflow | None | 0 | - |
The job-minutes are computed, because the repository is public and nothing was charged: each job’s seconds rounded up to a whole minute, which is GitHub’s rounding rule. A run cancelled before its job started has no job, so it costs no minutes. The last column is a median over the repetitions, with the fastest and slowest in brackets.
A group on its own drops the runs in the middle
Under a group with nothing else, run 1 started and ran to the end. Runs 2, 3 and 4 arrived while it was working. Each replaced the one before it, so 2 and 3 were cancelled by their successors and 4 by 5. None of them ever had a job, and none cost a minute. Run 5 waited for run 1 to finish and then ran. This is the setting for a deploy: nothing is interrupted, and the last commit is the one that is deployed. It is also why a group with no other options can look like a bug, because runs you expected to see are cancelled with no explanation beyond the replacement.
concurrency:
group: deploy-${{ github.ref }}
cancel-in-progress cuts the run that is working
With cancel-in-progress: true, a new run does not wait. It cancels the run that is working and takes its place. Five pushes, in all ten repetitions: runs 1, 3 and 4 were cancelled while their job was running, run 2 was cancelled before its job had started, and only run 5 finished. Those cut jobs used runner time, so they would be billed, and the median was 4 minutes against 2 for a group alone. The saving over no group is the finished work you did not need. The cost is that a run interrupted halfway is a half-done deployment if the job deploys.
Which runs are cut while running and which before they start depends on timing: a job that takes a few seconds to be given a runner is cut when its successor arrives before then. Do not rely on the pattern, only on the last row of it, that the newest run finishes. If some branches must not be interrupted, cancel-in-progress takes an expression, and GitHub’s documentation shows one that cancels everywhere except branches named release/.
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ !contains(github.ref, 'release/') }}
queue: max runs every run, one at a time
queue: max removes the replacement. In all ten repetitions all five runs finished, one at a time, and in the order they were pushed. The price is time and minutes: the last run waited a median of 213 seconds from the moment it was created until its job started, and the five runs took 299 seconds from first push to last job, against about 105 with no group, because the work is serial. It cost the same 5 minutes as no group. Use it when every run has to happen in order and none may be thrown away, such as a deploy that applies a migration per commit.
concurrency:
group: production-deploy
queue: max
There is a ceiling, and GitHub words it two ways. The concurrency page says that when the queue of 100 is full, additional runs are cancelled. The limits page says runs beyond the limit are rejected. We did not fill a queue, so we cannot say which you would see, only that the 101st run does not wait.
head_ref is empty on a push
GitHub’s documentation gives github.head_ref || github.run_id as a group that cancels superseded runs of a pull request. github.head_ref exists only on pull request events, so on a push the expression falls back to the run id, which is different for every run. Every run is then in a group of its own, and nothing is ever cancelled. We pushed five commits under it, five times, and all five runs finished each time. If the same workflow runs on pushes and on pull requests, key on github.ref instead, as GitHub’s own examples do.
Inside a matrix
A concurrency key on a job in a matrix is shared by every leg unless it names the leg. We ran a matrix of three legs with cancel-in-progress: true on the job and a group that did not mention the leg, so all three legs were in one group. The legs cancelled each other. Across five branches, 70 of the 75 jobs were cancelled and only 5 finished, one leg of the last run on each branch, with the other two cut. Every one of the 25 runs ended as cancelled, including the last. A matrix that is meant to test three things then tests one.
The job-level key can read matrix, which a workflow-level key cannot, so the fix is to put the leg in it. With the group below, the three legs of the first four runs were cancelled while running and all three legs of the last run finished, on all five branches. The cost is that each superseded leg is still billed for the time it ran: the median was 15 job-minutes for five pushes of a three-leg matrix, against 13 for the broken key that kept only one leg. One repetition of each took about 385 seconds instead of about 100, and we did not investigate why.
jobs:
test:
runs-on: ubuntu-24.04
strategy:
matrix:
leg: [a, b, c]
concurrency:
group: test-${{ github.ref }}-${{ matrix.leg }}
cancel-in-progress: true
queue: max with cancel-in-progress
GitHub says the pair is a validation error, and it is. We pushed five commits under queue: max with cancel-in-progress: true, five times. All 25 pushes produced a run that completed as a failure with no job in it, and the run carried the workflow file’s path in place of its name, which is how GitHub labels a workflow it could not read. No runner was involved and no minute was used. The mistake is cheap, but it also means the workflow does nothing, so a deploy you expected never happens. Look for a run named after the file.
Which setting for which workflow
For tests on pull requests and branches, use a group with cancel-in-progress: true. Nobody wants the result of a commit that has been superseded, and cutting it saves the runner time. For a deploy where only the newest commit matters, use a group on its own, so a deploy is never interrupted and the intermediate ones are dropped. For a deploy where every commit must run, in order, use queue: max and expect it to take as long as the runs take added together.
Two cautions apply to all of them. A group name is shared by every workflow in the repository, so a name that is not unique will cancel runs of another workflow, as GitHub’s documentation warns: put github.workflow in the key. And a run held by a group has no runner yet (the pending job in our other test had no runner assigned), so look for the other run in the group rather than at the runner list; see the guide to queued, pending and waiting runs. Cancelling superseded runs is one of the ways to run less, which is the subject of our post on cutting the work a workflow does, and the workflow checker flags a workflow that has no concurrency key. If you are putting a merge queue in front of a protected branch, the merge queue post covers the trigger it needs.
What we ran
All of it ran on 17 November 2026 on GitHub-hosted ubuntu-24.04 runners, in a public repository where standard runners are free. Eight workflows, the script that pushes and the script that reads the runs back, the method and every row, with the run id of each run, are in the B1 directory of runners-io/ci-measurements. One image, one day and a 40-second job: with a longer job or pushes further apart, the pattern under cancel-in-progress changes, and the one under a group alone does not. Build times measured on GitHub’s runner and on ours are on our faster GitHub Actions runners, measured page.
Sources
- Control the concurrency of workflows and jobs (docs.github.com)
- GitHub Actions concurrency groups now allow larger queues (GitHub changelog, 7 May 2026) (github.blog)
- Workflow syntax for GitHub Actions (docs.github.com)
- Actions runner pricing (docs.github.com)
- Actions limits (docs.github.com)
- B1: five pushes under each concurrency setting (runners-io/ci-measurements) (github.com)
Frequently asked questions
What does a concurrency group do in GitHub Actions?
It lets at most one run or job in the group work at a time. By default one more can wait, and a newer waiting run replaces the older one, which is cancelled. In our test of five pushes, runs 2, 3 and 4 were cancelled while pending.
Does cancel-in-progress cancel a run that is already running?
Yes. With cancel-in-progress: true, a new run cancels the run in progress in the same group as well as the one waiting. In our test only the newest of five runs finished, and the median was 4 job-minutes against 2 for a group alone.
What does queue: max do in GitHub Actions?
It lets up to 100 runs wait in a group instead of one, and runs them first in, first out. GitHub announced it on 7 May 2026, and it cannot be combined with cancel-in-progress: true. In our test all five runs ran, in push order, one at a time.
Why did my concurrency group never cancel anything?
A group keyed on github.head_ref only works on pull requests, because the value is empty on a push. With the run id as the fallback, each push gets a group of its own. In our test all five pushes ran. Key on github.ref instead.