Stop GitHub Actions deploys overlapping or running out of order
Short answer: Add a concurrency group to your deploy workflow or job so only one deploy to each environment runs at a time. With the default settings, a new run waits while the current one finishes, and any older run still waiting is cancelled in favour of the newest, so production always ends on the latest commit. Use cancel-in-progress: true for test runs on pull requests, where only the newest result matters, but think twice before using it on deploys, because stopping a deploy halfway can leave a server in a mixed state.
The problem: two pushes, two deploys
Without any controls, every push to main starts its own workflow run. If you push a fix two minutes after a feature, both runs build and deploy at the same time. Several things can go wrong:
- Both runs upload files or restart services at once, and the site is briefly broken.
- The first run takes longer (a slow test, a cold cache) and finishes after the second, so the older commit ends up live.
- Two database migrations run at the same moment.
- Your deploy notifications say the fix is live when it has been overwritten.
The second case is the sneaky one: everything reports success, yet production is running yesterday's code.
How concurrency groups work
GitHub's documentation describes the rule simply: there can be at most one running job or workflow in a concurrency group at any time. If another run in the same group is in progress, a newly queued run is pending. By default, any existing pending run in the group is cancelled and the new one takes its place.
That default fits deploys well. If three pushes land while a deploy is running, the middle one is skipped and the newest deploys once the current one finishes.
A deploy job with a group per environment looks like this:
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
concurrency:
group: deploy-production
steps:
- uses: actions/checkout@v5
- run: ./deploy.sh
Use a different group for staging so a staging deploy never blocks production, and vice versa.
cancel-in-progress: when to use it
Setting cancel-in-progress: true tells GitHub to cancel the currently running job in the group, not just pending ones, when a new run arrives.
That's ideal for checks on pull requests. When someone pushes three commits in a row to a branch, only the last test run matters, and cancelling the others saves runner minutes and gets feedback sooner. GitHub's docs show a pattern that groups by branch and falls back to the unique run ID for events where github.head_ref isn't defined:
group: ${{ github.head_ref || github.run_id }} with cancel-in-progress: true.
For deploys, cancelling halfway is riskier. If your deploy uploads files, runs migrations and restarts services as separate steps, a cancellation in the middle can leave new files with an old database, or one server updated and another not. Only use cancel-in-progress on deploys if every step is safe to interrupt and the next run will finish the job.
Keeping more than one run waiting
By default only one run waits in the group. GitHub's docs describe an optional queue property: single (the default) keeps at most one pending run, while max allows up to 100 pending runs, cancelling extras once the queue is full. You can't combine queue: max with cancel-in-progress: true. A longer queue is useful when every run must deploy in order, for example when each one carries a separate migration, though most teams prefer skipping to the newest commit.
Naming groups so they don't collide
Concurrency groups apply across the whole repository. GitHub warns that group names must be unique across workflows, or a run in one workflow can cancel runs in another. Include the workflow name in the group, such as ${{ github.workflow }}-${{ github.ref }}, for test runs, and an explicit environment name for deploys.
Watch for these mistakes:
- One group for everything, so a slow test run blocks a hotfix deploy.
- Branch name in a deploy group when several branches deploy to the same environment. Group by environment, not branch.
- Concurrency set on the workflow, but deploy happens in one job of several. Put it on the deploy job if tests can safely run in parallel.
Make out-of-order deploys visible
Even with concurrency in place, it's worth being able to see what's live:
- Have your deploy write the commit SHA to a version endpoint or a footer comment.
- Post the deployed SHA to your team chat at the end of each deploy.
- Check the deployed SHA matches the latest commit on
mainafter busy release days.
Database migrations deserve their own lock
If your app runs migrations at deploy time, concurrency groups stop two GitHub runs from migrating at once. They don't stop a migration started by another route, such as an app instance that runs migrations on boot. Many migration tools take their own database lock; check that yours does and that it's turned on.
A worked example
An illustrative Bristol online shop deployed from GitHub Actions on every push to main. One afternoon a hotfix went out, and an hour later customers saw the bug again. The earlier feature deploy had been slowed by a long test step and finished after the hotfix, putting the old code back. The team added concurrency: group: deploy-production to the deploy job, a separate group for staging, and cancel-in-progress only on pull request checks. Pushes made during a deploy now wait their turn, and the newest commit always deploys last.
FAQ
Does a cancelled pending run count as a failure?
It shows as cancelled, not failed. Notifications that only fire on failure won't trigger.
Can I see which run is waiting?
Yes. Pending runs show in the Actions tab with a note that they're waiting for a run in the same concurrency group.
Will this slow down my deploys?
Only when deploys overlap, and then waiting is what you want.
Should staging and production share a group?
No. Give each environment its own group so one never holds up the other.
If your deploys sometimes put the wrong version live, send us your workflow file and we'll help you add the right concurrency rules.