From 1d87b53cc8830559e01103fac31fa4e3c937e35e Mon Sep 17 00:00:00 2001 From: thodson-usgs Date: Thu, 25 Jun 2026 09:26:31 -0500 Subject: [PATCH] ci(docs): serialize gh-pages deploys to fix the "cannot lock ref" race Two commits landing on main within a couple of minutes spawn two "Sphinx Docs Build" runs that both force-push gh-pages via JamesIves/github-pages-deploy-action. The newer run reads the gh-pages tip, the older run advances it first, and the newer run's push is then rejected: ! [remote rejected] ... -> gh-pages (cannot lock ref 'refs/heads/gh-pages': is at but expected ) The Sphinx build itself succeeds; only the concurrent deploy loses the race. Add a workflow-level concurrency group keyed on the ref so runs targeting the same branch serialize instead of racing. cancel-in-progress is false so every commit's docs still deploy (the later run simply queues behind the earlier one and force-pushes on top). PR builds, which key on their own ref and don't deploy, are unaffected. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01Sjb14HkwuCydKSKMsaXsgd --- .github/workflows/sphinx-docs.yml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/workflows/sphinx-docs.yml b/.github/workflows/sphinx-docs.yml index 2018279e..2640e6b6 100644 --- a/.github/workflows/sphinx-docs.yml +++ b/.github/workflows/sphinx-docs.yml @@ -6,6 +6,15 @@ on: push: pull_request: +# Serialize runs for the same ref so two near-simultaneous pushes to main +# don't race to force-push gh-pages. Without this, the second deploy fails +# with "cannot lock ref 'refs/heads/gh-pages'" because the first run advanced +# the branch after the second had already read its tip. Queue rather than +# cancel (cancel-in-progress: false) so every commit's docs still deploy. +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: false + jobs: docs: runs-on: ubuntu-latest