ci: add scheduled audit-docs-paths workflow - #27245
Open
nickvigilante wants to merge 3 commits into
Open
Conversation
nickvigilante
force-pushed
the
vigilante/docs-366-wire-audit-docs-pathsmjs-to-run-on-a-github-actions-cron
branch
from
July 14, 2026 21:25
874c605 to
ca3ca60
Compare
nickvigilante
marked this pull request as ready for review
July 14, 2026 21:30
bpmct
approved these changes
Aug 5, 2026
bpmct
left a comment
Member
There was a problem hiding this comment.
LGTM assuming you have a solid solution for getting notified/assigned when a link is old/stale
Adds .github/workflows/audit-docs-paths.yaml running the docs-URL drift audit on a weekly cron and on demand. It checks out coder/coder and coder/coder.com, runs site/scripts/audit-docs-paths.mjs against both, and always uploads the dated report as an artifact and to the run summary. On findings it opens or updates a single deduplicated tracked issue and fails the run; on a clean run it closes that issue. The job is gated behind the AUDIT_DOCS_PATHS_ENABLED repository variable because the audit reads the private coder.com repo, which needs a dedicated GitHub App token that is not yet provisioned. This supersedes the dormant audit-docs-paths job previously embedded in weekly-docs.yaml, which is removed here to avoid a double run once the audit is enabled. Ref: DOCS-366
Swaps the private coder.com checkout from a to-be-provisioned dedicated GitHub App token to the existing cdrci2 machine-user token (secrets.CDRCI2_GITHUB_TOKEN), so no new App has to be stood up. Enabling is now just setting AUDIT_DOCS_PATHS_ENABLED=true once cdrci2's coder.com read access is confirmed. Ref: DOCS-366
nickvigilante
force-pushed
the
vigilante/docs-366-wire-audit-docs-pathsmjs-to-run-on-a-github-actions-cron
branch
from
August 6, 2026 16:06
ca3ca60 to
1fead48
Compare
Contributor
Author
|
Follow-up: stacked PR #27924 wires the Also: I rebased this branch onto Tracked in DOCS-617. |
nickvigilante
enabled auto-merge (squash)
August 6, 2026 17:44
nickvigilante
disabled auto-merge
August 6, 2026 17:44
cdrci2 is not a collaborator on coder/coder.com, so its token cannot read the repo. cdrci is a coder.com collaborator, and its token (secrets.CDRCI_GITHUB_TOKEN) is already used for cross-repo checkouts in release.yaml/tag-and-release.yaml, so use that for the coder.com checkout. Ref: DOCS-366
nickvigilante
force-pushed
the
vigilante/docs-366-wire-audit-docs-pathsmjs-to-run-on-a-github-actions-cron
branch
from
August 6, 2026 17:46
1fead48 to
d5ba3cd
Compare
nickvigilante
enabled auto-merge (squash)
August 6, 2026 17:46
nickvigilante
disabled auto-merge
August 6, 2026 17:46
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
schedule(weekly, Monday 09:00 UTC — same cadence asweekly-docs) andworkflow_dispatch.coder/coder(root) andcoder/coder.com(intocoder.com/, read with thecdrciCI-bot token). The audit covers references in both repos.--roots(required, otherwise the report can't classify findings by repo).audit-docs-paths-reportartifact and writes it to the run summary.Enabling (dormant until then)
The audit reads coder/coder.com, a private repo, which the default
GITHUB_TOKENcan't read, so the coder.com checkout uses the existingcdrciCI-bot token (secrets.CDRCI_GITHUB_TOKEN) — already used for cross-repo checkouts inrelease.yaml/tag-and-release.yaml, andcdrciis a coder.com collaborator (verified). No new App to stand up. The job is gated behindvars.AUDIT_DOCS_PATHS_ENABLEDso it merges dormant and can be validated before going live.To turn it on:
vars.AUDIT_DOCS_PATHS_ENABLED = 'true'.workflow_dispatchto confirm the end-to-end run.Also in this PR
Removes the dormant
audit-docs-pathsjob embedded inweekly-docs.yaml(added in #25740, gated off pending the same credential). The new dedicated workflow supersedes it; theweekly-docs.yamldiff is exactly that job removal.Validation
actionlint -shellcheck= -ignore set-outputpasses locally; PRtitle,lint-actions, andlint-docsare green.cdrciis a collaborator on coder/coder.com (read access confirmed);secrets.CDRCI_GITHUB_TOKENalready exists in this repo. (Note:cdrci2is not a coder.com collaborator, so an earlierCDRCI2_attempt was corrected toCDRCI_.)main(both repos): 0 findings — 148/docs/*redirect rules indexed; 1846 coder/coder + 432 coder.com TS/TSX files scanned. So aworkflow_dispatchonmaintoday 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
AUDIT_DOCS_PATHS_ENABLEDand removed the embedded job rather than adding a second gate..yamlto match the repo's other docs workflows (the issue text said.yml).Linear: https://linear.app/codercom/issue/DOCS-366