GitHub Actions Concurrency: Cancel Stale PR Runs Without Cancelling Main
Stop obsolete pull-request checks while preserving main-branch builds. A worked concurrency-group pattern explains running versus pending cancellations and how to verify the result.
TL;DR
- Group PR runs by workflow and PR number, and give each push a unique run-ID group.
- Set cancel-in-progress only when github.event_name is pull_request, so main builds are never cancelled.
- Test with two commits on a PR and two on a safe branch; keep deployments out of cancellable groups.
A pull request gets three quick commits. GitHub Actions starts three test runs, but only the latest commit matters for the review. Meanwhile, someone pushes to main and discovers an important build was cancelled by a shared concurrency rule. The problem is not a slow runner: it is how the workflow groups runs.
For ordinary pull-request CI, group runs by workflow and pull-request number, cancel an older run when that PR receives another update, and keep `push` runs in distinct groups. GitHub's concurrency documentation supports conditional cancellation. The part you must design yourself is the group key: runs that share it can affect each other even if they originate from different workflow files.
This guide is for maintainers of GitHub.com repositories using a pull_request workflow to check contributor changes and a push workflow for a protected branch. It explains the current GitHub Actions behaviour as documented on 8 November 2026. The configuration is an illustrative template; replace its test step with your project’s real test command. It has been checked against GitHub documentation and parsed as YAML locally, not executed on a hosted runner.
Why cancel-in-progress: false is not enough
GitHub's concurrency setting works at either workflow or job scope. With the usual queue: single behaviour, one member of a concurrency group can run while one newer member waits. When another run joins, the older pending one is cancelled and replaced—even if cancel-in-progress is false. Setting it to true additionally cancels the running member of that group. See GitHub's current queue semantics.
That means the following seemingly harmless rule is unsuitable when you need every push build to finish:
concurrency:
group: checks-main
cancel-in-progress: false Every run of every workflow in this repository that uses checks-main competes for the same group. One main-branch run may continue, but another pending main run may be replaced. If you set cancel-in-progress: true, even running main builds can be cancelled. The fixed text also makes PRs compete with one another.
A branch-specific rule such as ${{ github.workflow }}-${{ github.ref }} is better, but it still groups all pushes to main together. Whether that is desirable depends on your release policy. The workflow syntax reference defines both job-level and top-level concurrency.
A workflow that cancels stale PR checks but preserves push runs
Place the following in a workflow under .github/workflows/, then substitute your own commands in the run step. The example is intentionally minimal and asks only for read access to repository contents:
name: PR and main checks
on:
pull_request:
branches: [main]
push:
branches: [main]
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || format('run-{0}', github.run_id) }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
verify:
runs-on: ubuntu-latest
steps:
- name: Show where the project's checks belong
run: echo 'Replace this step with the repository test command' What the expression does: For a pull request, the group becomes a name like PR and main checks-pr-84. A new commit to that same PR reuses that group and cancels its older running check. PR 85 has a different group and is not cancelled by PR 84. For a push, the group includes run- and the unique github.run_id, so each push has its own group: it neither cancels nor displaces other push runs by concurrency. The conditional cancel-in-progress applies only when github.event_name is pull_request.
This is different from merely putting cancel-in-progress: false on main: the unique group prevents even the default pending-run replacement. The github.workflow prefix keeps this example separate from other workflows with different names. GitHub notes that concurrency names are case-insensitive, so do not build your isolation strategy around capitalisation.
The expression uses GitHub's documented `format()`, `&&` and `||` operators and the `github.event_name` / `github.run_id` contexts. As with other && … || expressions, the middle value must not be empty or false; format('pr-{0}', number) produces a nonempty result for an ordinary pull-request event. The push branch explicitly uses the unique run ID.
What will happen to the runs?
*Illustrative concurrency-group outcomes; not a screenshot of real GitHub runs.*
| New event | Its group | Expected consequence |
|---|---|---|
| PR #84 opens | …-pr-84 | Its first check starts or waits for capacity. |
| PR #84 gets another commit | …-pr-84 | Its previous running or pending check is cancelled; the newer check takes its place. |
| PR #85 opens | …-pr-85 | Independent of #84's concurrency group. |
| Commit pushed to main | …-run-12345 | Independent of the PR groups and other push run IDs. |
| Another commit pushed to main | …-run-12346 | Does not cancel or replace the previous push via this rule. |
These group names are illustrative, not observed GitHub run IDs. Concurrency does not promise that a job starts immediately: runner availability, approval requirements, repository limits and other policies still apply. The events reference also explains that for an open pull_request, github.ref normally names a PR merge ref (refs/pull/84/merge), whereas for push it names the pushed branch. That is another reason to choose the grouping key consciously rather than assuming both events represent a normal branch.
Check the cancellation logic before adding real work
If this is an established repository, do not replace its existing workflow with the sample. Instead, copy only its concurrency block, keep its current triggers and jobs, and inspect the change in a PR. If the workflow has workflow_dispatch, scheduled events or other triggers, the fallback run-ID branch keeps those runs isolated too, but verify that this matches their operational purpose. A manual release operation may need a single serial deployment group, not a unique group for each run.
Before merging, write down the intended outcomes for five test events: PR A first commit, PR A second commit, PR B first commit, main push 1 and main push 2. Compare them with the table above. Then exercise the rule on a low-risk test branch or nonproduction repository where cancelling a run is acceptable. GitHub's Actions run history guide explains where to inspect each run's status and logs; with GitHub CLI, gh run list --workflow YOUR_WORKFLOW and gh run view RUN_ID provide another way to review actual outcomes.
A meaningful verification has both halves: an older PR run genuinely becomes cancelled when a newer commit arrives, and a main push run is not cancelled when another main push follows. If a run is still queued rather than in progress, observe the pending-state behaviour separately. A local YAML parser can catch indentation mistakes; it cannot prove GitHub's scheduling behaviour or repository policy interactions.
For a small team, you can test the group calculation without committing a workflow by following the five event cases above. But only an actual GitHub run establishes the outcome in your repository, especially when organization-level execution policies or self-hosted runner constraints apply.
Three ways teams accidentally cancel the wrong work
One hard-coded group across workflows. A name like ci is repository-scoped. If your build.yml and deploy.yml both use it, a build can cancel or displace a deployment. Add a workflow-specific prefix unless the cross-workflow competition is deliberate. GitHub warns about this in its concurrency examples.
Using `github.head_ref` without considering forks. On a PR event it identifies the source branch, but two contributors can use the same branch name. Prefer the PR number for checks attached to a particular PR, and handle events that have no head ref. GitHub's contexts reference describes when the head ref is available.
Treating cancellation as a deployment lock. A cancellable test job is different from a migration, package publication or production deployment. Do not let a newer commit interrupt a migration halfway through. If production work must execute sequentially, consider its own deployment group with no in-progress cancellation. The current GitHub documentation also describes queue: max for up to 100 pending jobs or workflow runs in a group; it cannot be combined with cancel-in-progress: true. Decide whether you want to discard stale work or preserve a queue, not both.
If checks run contributor code, keep pull_request and minimal token permissions unless your design genuinely needs more. GitHub's guide to GITHUB_TOKEN recommends granting only the permissions required. If you have a pull_request_target workflow, the security implications are different; Jitsumi's guide to auditing `pull_request_target` before the December 2026 policy change explains that separate decision. Concurrency settings do not make a privileged event safe.
When not to cancel old runs
Cancel stale PR checks when you only need feedback about the current proposed change and your repository's review rules tolerate cancelled superseded checks. Preserve runs that publish artifacts, perform database operations, create release attestations, or update production, unless their cancellation and recovery semantics were explicitly designed and tested. A cancel-in-progress expression governs *which run GitHub stops*, not whether your application can recover from a partially completed operation.
For a workflow that must process every main commit exactly once, do not use a branch group with default queue: single. The example's distinct run-ID groups avoid cancellation by concurrency, but they do not guarantee chronological execution or prevent overlap. If you require ordered, nonoverlapping deployment work, model that as a separate deployment queue with its own controls and verify the repository's supported Actions version and policy.
The reliable test is simple: push two commits to one test PR and confirm that the older check is replaced; push two commits to the protected branch in a safe environment and confirm both runs remain eligible to finish. When those outcomes agree with your intention, you have solved the wasted-PR-run problem without silently turning the release branch into collateral damage.
Sources and further reading
Subscribe
All the new articles in one Monday digest. Unsubscribe with one click.