ci(docs): serialize gh-pages deploys to fix the "cannot lock ref" race (DOI-USGS#339)

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 <new> but expected <old>)

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.


Claude-Session: https://claude.ai/code/session_01Sjb14HkwuCydKSKMsaXsgd

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: thodson-usgs

.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