From 95002eda2d57986cbb48d1aff3ff33f459bc2a6f Mon Sep 17 00:00:00 2001 From: Gaurav Trivedi Date: Wed, 13 May 2026 18:39:25 +0530 Subject: [PATCH] ci: fix docs publishing by removing tag indirection The previous workflow used a two-step process: the tag job force-tagged the commit as `docs`, expecting the tag push to trigger build and deploy jobs. This never worked because GitHub Actions does not trigger workflows from tag pushes made with GITHUB_TOKEN (by design, to prevent loops). Fix: run check, build, and deploy as sequential jobs in a single workflow invocation. The check job determines if the pushed branch is the latest release branch, and build/deploy gate on its output. Also update docs/README.md to reflect the new workflow design. Co-Authored-By: Claude Opus 4.6 --- .github/workflows/docs.yml | 34 ++++++++++++++++++++-------------- docs/README.md | 32 ++++++++++++++++---------------- 2 files changed, 36 insertions(+), 30 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index bbb396323..3268acc9c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -8,8 +8,6 @@ on: - 'docs/**' - 'antora-playbook.yml' push: - tags: - - docs branches: - 'release-*' @@ -23,9 +21,11 @@ concurrency: cancel-in-progress: false jobs: - tag: + check: if: github.event_name == 'push' && startsWith(github.ref, 'refs/heads/release-') runs-on: ubuntu-latest + outputs: + is-latest: ${{ steps.check.outputs.match }} steps: - name: Check if this is the latest release branch id: check @@ -35,7 +35,7 @@ jobs: | sed 's|.*refs/heads/release-||' \ | sort -t. -k1,1n -k2,2n \ | tail -1)" - + if [ "$CURRENT_BRANCH" = "$LATEST_BRANCH" ]; then echo "Branch $CURRENT_BRANCH is the latest release branch." echo "match=true" >> "$GITHUB_OUTPUT" @@ -44,18 +44,27 @@ jobs: echo "match=false" >> "$GITHUB_OUTPUT" fi + validate: + if: github.event_name == 'pull_request' + runs-on: ubuntu-latest + steps: - name: Checkout - if: steps.check.outputs.match == 'true' uses: actions/checkout@v4 - - name: Force-tag current commit as docs - if: steps.check.outputs.match == 'true' - run: | - git tag -f docs - git push origin docs --force + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install Antora and extensions + run: npm i -g @antora/cli@3.1 @antora/site-generator@3.1 @antora/lunr-extension@1.0.0-alpha.13 + + - name: Build site + run: SITE_SEARCH_PROVIDER=lunr antora --fetch antora-playbook.yml build: - if: github.event_name == 'pull_request' || (github.event_name == 'push' && github.ref == 'refs/tags/docs') + if: needs.check.outputs.is-latest == 'true' + needs: check runs-on: ubuntu-latest steps: - name: Checkout @@ -73,17 +82,14 @@ jobs: run: SITE_SEARCH_PROVIDER=lunr antora --fetch antora-playbook.yml - name: Disable Jekyll - if: github.ref == 'refs/tags/docs' run: touch build/site/.nojekyll - name: Upload artifact - if: github.ref == 'refs/tags/docs' uses: actions/upload-pages-artifact@v3 with: path: build/site deploy: - if: github.event_name == 'push' && github.ref == 'refs/tags/docs' needs: build runs-on: ubuntu-latest environment: diff --git a/docs/README.md b/docs/README.md index bcc14ba2c..cd1f6d387 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,8 +11,6 @@ This directory contains the [Antora](https://antora.org/)-based documentation fo | `main` | Development branch. All new doc work starts here. | | `release-X.Y` | Release branches (e.g., `release-0.1`). The **latest** release branch is the source for the published site. | -The `docs` **tag** (not a branch) is managed automatically by CI. Do not create or move it manually. - ## Contributing documentation changes ### Day-to-day workflow @@ -53,34 +51,36 @@ When a new release branch is created (e.g., `release-0.2`): ## How publishing works -Publishing is fully automated via GitHub Actions (`.github/workflows/docs.yml`). There are three jobs: +Publishing is fully automated via GitHub Actions (`.github/workflows/docs.yml`). The workflow has four jobs: -### 1. `tag` job (runs on push to any `release-*` branch) +### 1. `check` job (runs on push to any `release-*` branch) -- Queries all remote `release-*` branches. +- Queries all remote `release-*` branches using `git ls-remote`. - Sorts them by semver to find the latest (e.g., `release-0.2` > `release-0.1`). -- If the pushed branch **is** the latest: force-tags the commit as `docs` and pushes the tag. -- If the pushed branch is **not** the latest: skips silently. +- Outputs `is-latest=true` if the pushed branch is the latest, `false` otherwise. + +### 2. `validate` job (runs on PRs to `main`) -### 2. `build` job (runs on `docs` tag push or PR to `main`) +- Builds the site with Antora to verify the docs compile without errors. +- Does **not** deploy. This is a build-only check. -- Checks out the tagged commit. +### 3. `build` job (runs after `check`, only if `is-latest` is `true`) + +- Checks out the release branch. - Installs Antora 3.1 and the Lunr search extension. - Runs `antora --fetch antora-playbook.yml` to build the site. +- Creates a `.nojekyll` file (required for GitHub Pages to serve Antora assets). - Uploads the build output as a GitHub Pages artifact. -- On PRs to `main`, it only validates the build (no artifact upload, no deploy). -### 3. `deploy` job (runs on `docs` tag push, after `build` succeeds) +### 4. `deploy` job (runs after `build` succeeds) - Deploys the artifact to GitHub Pages. ``` -PR to main ──> build (validate only, no deploy) - -Push to release-* ──> tag job ──> is this the latest? ──yes──> force-tag as `docs` - ──no──> skip +PR to main ──> validate (build-only check, no deploy) -docs tag push ──> build ──> deploy to GitHub Pages +Push to release-* ──> check ──> is this the latest? ──yes──> build ──> deploy + ──no──> skip (all remaining jobs skipped) ``` ## Local build