mirror of
https://github.com/coder/coder.git
synced 2026-09-21 20:51:01 +08:00
Nick Vigilante
c13dd06d2f
The `audit-docs-paths` job in `weekly-docs.yaml` fetches a config file from a private upstream source. An anonymous read returns 404 and the job fails on every weekly run, firing a misleading "Stale docs paths found in site/src/" Slack notification (a pre-existing bug in the notification copy, tracked separately). We originally tried to authenticate the fetch with the existing CI token used for cross-repo work (the same one used by `contrib.yaml`), but that token does not have read access to the upstream source. The proper fix is a GitHub App scoped to cross-repo `Contents: Read`; the docs team is tracking the App provisioning internally. Until the App is provisioned, this PR disables the job behind a `vars.AUDIT_DOCS_PATHS_ENABLED` repository variable. The variable is unset, so the job skips on the weekly cron and on `workflow_dispatch`. The other two jobs in this workflow (`prepare-linkspector-browser`, `check-docs`) keep running normally, so docs PRs still get link-checked. Re-enabling once the App is provisioned is a one-line change: set `AUDIT_DOCS_PATHS_ENABLED` to `'true'` on this repo, no workflow edit required. <details> <summary>Investigation log (why the App is needed)</summary> Initial attempt (commits `5cca548`, `fc0ff59`, now discarded) authenticated the fetch via the GitHub Contents API with `Accept: application/vnd.github.raw` and an existing CI token already used for cross-repo writes. `coder-agents-review` approved that approach in Round 2 ([review 4546533491](https://github.com/coder/coder/pull/26571#pullrequestreview-4546533491)), and all 29 CI checks passed. Validation via `workflow_dispatch` (run [27973114839](https://github.com/coder/coder/actions/runs/27973114839)) failed at the fetch step with `curl: (22) The requested URL returned error: 404`. The bare `curl` against the same URL with a personal access token returned HTTP 200 and valid JSON, so the call shape was correct; the CI token just lacks the necessary scope on the upstream source. The Contents API returns 404 (not 403) when a token cannot see a private repository, which is why the original failure mode was hard to attribute. Options considered: 1. **Extend the existing CI token** to include the missing read access. Cheapest in lines of code, but the token is org-CI-owned and changing its scope has blast radius beyond this job. 2. **New fine-grained PAT.** Tightest scope, but PATs are user-owned. If the issuing user leaves the org, the token auto-revokes and the audit silently breaks again, which is exactly the failure mode this PR is trying to make less likely. 3. **GitHub App owned by the org.** Tied to the org, not a user; survives staff turnover; least-privileged per repo. Heaviest setup because creation, installation, and secret provisioning all need org admin. Option 3 is the right long-term answer but is not same-day. Disabling the job is the smallest change that stops the noise immediately, and the feature-flag variable keeps the re-enable path to one step. </details> <details> <summary>Validation</summary> * `actionlint` clean on `.github/workflows/weekly-docs.yaml`. * Branch passed all 29 CI checks under the previous authentication approach; this revision is strictly smaller (one job-level `if` guard + comments), no new failure surface introduced. * The disable cannot be tested end-to-end without merging, since the affected job runs on `schedule` / `workflow_dispatch` against `main`. Once merged: confirm the next weekly run (or a manual `workflow_dispatch`) shows `audit-docs-paths` as skipped, with no Slack notification. </details> --- > Generated by [Coder Agents](https://coder.com) on behalf of @nickvigilante.