From 95d0b354abe6f1dc5fa8bd147461b2db82d536ea Mon Sep 17 00:00:00 2001 From: Chris Mattmann Date: Tue, 10 Nov 2026 12:46:32 -0800 Subject: [PATCH] Stop running the documentation workflow twice per push The Documentation badge reads failing after almost every merge to master, and the docs are fine. Two runs start on every push and compete for the same concurrency group: CI push success 2026-11-09T22:00:27Z Documentation push cancelled 2026-11-09T22:00:27Z Documentation push cancelled 2026-11-09T21:59:51Z CI push success 2026-11-09T21:59:51Z Same timestamps. ci.yml had a `docs` job calling documentation.yml via workflow_call, and documentation.yml also triggers on push to master. Both hold `concurrency: group: "pages"`, so one is cancelled -- and GitHub renders a cancelled run as a failing badge, on the workflow the README badge points at. It is worse than a cosmetic problem. Under workflow_call from a push, github.event_name is still 'push', so the deploy job's `if` was true in the called run as well: both runs were deploying the same commit to Pages, and only the concurrency group kept them from doing it at once. So ci.yml no longer calls it, and documentation.yml takes `pull_request` instead -- which is what the ci.yml job was really providing, a docs build on pull requests. Deployment is still gated on a push to master, so a pull request builds the docs without publishing them. One run per event now. The concurrency group moves from the workflow to the deploy job. At workflow level it could cancel a queued *build*, which is how an ordinary pair of merges 36 seconds apart produced a failing badge over documentation that had built perfectly well. Deployments still serialise, which is what Pages needs, and an in-progress deployment is still allowed to finish. Checked before changing the job names: master has no branch protection and no required status checks, so dropping `docs / Build documentation with Sphinx` from the CI run breaks no gate. The same check now arrives from the Documentation workflow. Residual case, much narrower: three or more pushes to master inside a single deploy still leaves a superseded deployment cancelled. Skipping the docs deployment for a commit that is already two commits stale is the right outcome; it just means the badge can still go red in that case. --- .github/workflows/ci.yml | 3 --- .github/workflows/documentation.yml | 20 +++++++++++++------- 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7281ba8..1886c7e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -64,6 +64,3 @@ jobs: with: parallel-finished: true base-path: tika - - docs: - uses: ./.github/workflows/documentation.yml diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index bc8ae3c..ca81fbc 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -3,19 +3,18 @@ name: Documentation on: push: branches: ["master"] - workflow_call: + # Pull requests build the docs but do not deploy them; the deploy job is + # gated on a push to master. This replaces the `docs` job that ci.yml used + # to run, which called this workflow on the same push that already + # triggered it -- two runs, one pages concurrency group, and the loser was + # cancelled. A cancelled run renders as a failing badge. + pull_request: # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # Set permissions at the job level. permissions: {} -# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. -# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. -concurrency: - group: "pages" - cancel-in-progress: false - jobs: build: name: Build documentation with Sphinx @@ -53,6 +52,13 @@ jobs: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-slim + # Only the deployment is serialised. Putting this at workflow level meant a + # queued *build* could be cancelled too, which turned an ordinary pair of + # merges into a failing documentation badge even though the docs built + # fine. In-progress deployments are still allowed to finish. + concurrency: + group: "pages" + cancel-in-progress: false steps: - name: Deploy to GitHub Pages id: deployment