From a9a2fbd74f5dcca0da03689017003c040ba5ec95 Mon Sep 17 00:00:00 2001 From: Tejas Chopra Date: Tue, 4 Aug 2026 16:06:44 -0700 Subject: [PATCH] ci(docs): deploy Pages on wiki changes, drop the never-working Vercel job (#2746) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description Two independent bugs in `.github/workflows/docs.yml`. **1. Pages went stale because the push filter watched the wrong directory.** `mkdocs.yml` sets `docs_dir: wiki`, but the push filter listed `docs/**` and not `wiki/**`. So a merge touching only `wiki/` never triggered the workflow and the published Pages site silently went stale, while a `docs/**`-only change triggered a Pages rebuild whose sources mkdocs doesn't even read. Push now filters on `wiki/**` + `mkdocs.yml`. **Pull requests keep `docs/**`**, so `validate-nextjs` still catches a broken MDX change before merge. **2. `deploy-vercel` never worked — it wasn't a working path that went stale.** It ran `npx vercel deploy --prod --token=${{ secrets.VERCEL_TOKEN }}`, but those secrets don't exist: ```text $ gh api repos/headroomlabs-ai/headroom/actions/secrets --jq '.secrets[].name' | grep -i vercel (nothing) $ gh api orgs/headroomlabs-ai/actions/secrets --jq '.secrets[].name' | grep -i vercel (nothing) ``` So it invoked the CLI with an empty `--token=` and exited 1, every time: ```text 30 failed runs on main, 2026-07-14 .. 2026-08-04 most recent: 30874173333 13a310a0 failure 30845343100 6422a80a failure 30810614546 007446c7 failure per-job on 30874173333: failure Deploy Vercel Docs success Deploy GitHub Pages <- same run skipped Validate mkdocs build skipped Validate Next.js build ``` `deploy-github-pages` succeeded in those same runs, so this job contributed nothing but a red X on every merge to main. The Next.js site is published by **Vercel's own Git integration**, which is what has actually been deploying it. Removing this job leaves exactly one deploy path per site: Pages via mkdocs here, Vercel via its Git integration. ## Why this PR previously said the opposite I opened this as "drop the redundant Vercel job", then converted it to draft and posted a correction saying the deletion was **wrong** — because at that point the Vercel site had been stale since mid-June and this looked like the only deploy path. That correction was itself based on a wrong assumption: with no `VERCEL_TOKEN` configured, this job could never have deployed anything. It wasn't the deploy path; it was a job that had always failed. The site was stale because *nothing* was publishing it until the Git integration was connected. So: original intent right, first correction wrong, and the evidence above is what settles it. Recording that rather than quietly re-flipping the description. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) ## Changes Made - Push filter: `docs/**` → `wiki/**` (what mkdocs actually reads). - Removed the `deploy-vercel` job. - Replaced it with a comment recording *why* there is no Vercel job here, so nobody re-adds one. ## Testing - [x] Linting passes — workflow YAML parses, and the resulting shape is what's intended: ```text jobs: ['validate-mkdocs', 'validate-nextjs', 'deploy-github-pages'] push paths: ['wiki/**', 'mkdocs.yml', '.github/workflows/docs.yml'] pr paths: ['docs/**', 'wiki/**', 'mkdocs.yml', '.github/workflows/docs.yml'] ``` CI is the real check for a workflow change. The observable proof after merge is that the next push to `main` no longer reports a failing `Deploy Vercel Docs`, and that a `wiki/**`-only change triggers a Pages deploy (it currently does not). ## Real Behavior Proof - **Environment:** GitHub Actions on `headroomlabs-ai/headroom`, branch `main`. - **Exact command / steps:** `gh run list --workflow "Deploy Documentation" --branch main`; `gh api .../actions/secrets`; `gh run view --json jobs`. - **Observed result:** 30 consecutive `Deploy Documentation` failures on main attributable solely to `Deploy Vercel Docs`; no Vercel secrets configured at repo or org level; `Deploy GitHub Pages` green throughout. ## What this does NOT fix This is unrelated to the failing **`Vercel`** check currently showing on ~18 open PRs. That one comes from the Vercel GitHub App with `Authorization required to deploy.` — Vercel asking each PR author to authorize its app — and is a Vercel-side setting, not a workflow file. Two different mechanisms that both say "Vercel": | | mechanism | where it fails | fixed here? | |---|---|---|---| | `Deploy Vercel Docs` | Actions job in this file | pushes to `main` | **yes** | | `Vercel` / `Vercel Preview Comments` | Vercel GitHub App | contributor PRs | no — dashboard setting | For the record: `Vercel` is not a required status check (`template`, `label`, `merge-conflicts`, `no-manual-changelog`, `Secret scan (gitleaks)` are), so it has never actually blocked a merge. --- .github/workflows/docs.yml | 48 ++++++++++++++------------------------ 1 file changed, 18 insertions(+), 30 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 41712e4a9..e22833c03 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -8,11 +8,18 @@ on: - 'wiki/**' - 'mkdocs.yml' - '.github/workflows/docs.yml' + # Push only deploys GitHub Pages, and `mkdocs.yml` sets `docs_dir: wiki` — so the + # sources that matter here are wiki/ and mkdocs.yml, NOT docs/ (that is the + # Next.js site, which Vercel deploys through its own Git integration). + # + # wiki/** was missing, so a merge touching only wiki/ never triggered this + # workflow and the published Pages site silently went stale. docs/** was present + # but mkdocs never reads it, so it only bought a no-op Pages rebuild. push: branches: - main paths: - - 'docs/**' + - 'wiki/**' - 'mkdocs.yml' - '.github/workflows/docs.yml' workflow_dispatch: @@ -99,32 +106,13 @@ jobs: - name: Build and deploy run: mkdocs gh-deploy --force - deploy-vercel: - name: Deploy Vercel Docs - if: >- - github.event_name != 'pull_request' - && github.ref == 'refs/heads/main' - && github.repository_owner == 'headroomlabs-ai' - runs-on: ubuntu-latest - permissions: - contents: read - steps: - - uses: actions/checkout@v6 - - - name: Setup Node.js - uses: actions/setup-node@v6 - with: - node-version: '20' - cache: npm - cache-dependency-path: docs/package-lock.json - - - name: Install dependencies - run: npm ci - working-directory: docs - - - name: Deploy to Vercel - run: npx vercel deploy --prod --token=${{ secrets.VERCEL_TOKEN }} - working-directory: docs - env: - VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} - VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }} +# The Next.js docs site is deployed by Vercel's own Git integration, so there is no +# deploy job for it here. A `deploy-vercel` job used to run `npx vercel deploy +# --prod` on every push to main, but VERCEL_TOKEN / VERCEL_ORG_ID / +# VERCEL_PROJECT_ID are not configured as secrets (repo or org), so it invoked the +# CLI with an empty `--token=` and exited 1. It therefore never deployed anything: +# 30 failed runs on main between 2026-07-14 and 2026-08-04. `deploy-github-pages` +# succeeded in those same runs — only this job failed — so the red was pure noise. +# +# `Validate Next.js build` above still guards docs/** on pull requests, so a broken +# MDX change is caught before merge.