mirror of
https://github.com/coder/coder.git
synced 2026-10-31 19:36:41 +08:00
Nick Vigilante
2f34e1abd0
## What Adds `.github/workflows/audit-docs-paths.yaml`, a scheduled workflow that runs the docs-URL drift audit (`site/scripts/audit-docs-paths.mjs`, added in #25740) on a weekly cron and on demand, so drift is caught automatically instead of only when someone runs the script by hand. Scheduling was suggested by @bpmct on #25740. ## How it works - **Triggers:** `schedule` (weekly, Monday 09:00 UTC — same cadence as `weekly-docs`) and `workflow_dispatch`. - **Checks out both repos:** `coder/coder` (root) and `coder/coder.com` (into `coder.com/`, read with the `cdrci` CI-bot token). The audit covers references in both repos. - **Runs the audit** with absolute `--roots` (required, otherwise the report can't classify findings by repo). - **Always** uploads the dated report as the `audit-docs-paths-report` artifact and writes it to the run summary. - **On findings:** opens or updates a single deduplicated tracked issue with the report, and fails the run (red check). **On a clean run:** closes that issue. ## Enabling (dormant until then) The audit reads **coder/coder.com, a private repo**, which the default `GITHUB_TOKEN` can't read, so the coder.com checkout uses the existing **`cdrci`** CI-bot token (`secrets.CDRCI_GITHUB_TOKEN`) — already used for cross-repo checkouts in `release.yaml`/`tag-and-release.yaml`, and `cdrci` is a coder.com collaborator (verified). No new App to stand up. The job is gated behind `vars.AUDIT_DOCS_PATHS_ENABLED` so it merges dormant and can be validated before going live. To turn it on: 1. Set `vars.AUDIT_DOCS_PATHS_ENABLED = 'true'`. 2. Run once via `workflow_dispatch` to confirm the end-to-end run. ## Also in this PR Removes the dormant `audit-docs-paths` job embedded in `weekly-docs.yaml` (added in #25740, gated off pending the same credential). The new dedicated workflow supersedes it; the `weekly-docs.yaml` diff is exactly that job removal. ## Validation - `actionlint -shellcheck= -ignore set-output` passes locally; PR `title`, `lint-actions`, and `lint-docs` are green. - **Credential check:** `cdrci` is a collaborator on coder/coder.com (read access confirmed); `secrets.CDRCI_GITHUB_TOKEN` already exists in this repo. (Note: `cdrci2` is *not* a coder.com collaborator, so an earlier `CDRCI2_` attempt was corrected to `CDRCI_`.) - **Pre-flight audit against current `main` (both repos): 0 findings** — 148 `/docs/*` redirect rules indexed; 1846 coder/coder + 432 coder.com TS/TSX files scanned. So a `workflow_dispatch` on `main` today passes green with no issue filed (the "empty audit succeeds" criterion). The failure path can be checked by injecting a stale path on a throwaway branch. ## Decisions for review - **Mechanism** = tracked issue + failed check + artifact ("both" from the issue). Easy to narrow to issue-only or fail-only. - Reused `AUDIT_DOCS_PATHS_ENABLED` and removed the embedded job rather than adding a second gate. - Named the file `.yaml` to match the repo's other docs workflows (the issue text said `.yml`). Linear: https://linear.app/codercom/issue/DOCS-366