ci(.github/workflows): deep-link docs preview to first changed page#24832
Conversation
…hanged page Make the docs-preview comment link directly to the first added, modified, or renamed Markdown page under docs/ instead of the docs root for the branch. If a PR only deletes Markdown files (or only changes non-Markdown files such as images or manifest.json), no comment is posted.
|
/coder-agents-review |
There was a problem hiding this comment.
Clean, well-scoped improvement. The path-mapping logic is correct across all 452 current doc files. The PR description is thorough: it shows the problem, the mechanism, proof against a real PR, and local test output. Commit message and scope are proportional.
Severity count: 4 P3, 1 Nit, 1 Note.
DEREM-1 through DEREM-2 are tightly related: separating the gh api call from the grep | head pipeline fixes both (API errors propagate, log message becomes accurate). DEREM-4 proposes a structural simplification of the mapper that was verified against all test cases plus adversarial inputs.
Pariston ran a differential diagnosis of four problem framings and concluded the chosen approach is proportional. Mafu-san and Chopper found no issues beyond DEREM-1. Mafuuu confirmed all five documented contracts are kept by the implementation.
As Hisoka put it: "the comment names only the least interesting" of the three failure modes sharing that || true.
🤖 This review was automatically generated with Coder Agents.
- Separate gh-api call from grep/head pipeline so API failures (network, auth, rate-limit) propagate instead of being silently swallowed by `|| true` (DEREM-1, DEREM-2). - Commit path-mapper regression tests covering all five case branches plus edge cases for deeper nesting (DEREM-3).
shfmt enforces tab indentation by default in CI; the test file landed with two-space indents and broke the fmt job. Run shfmt -w to bring it into compliance.
Description
The
docs-previewworkflow currently links to the docs root for thebranch (e.g.
https://coder.com/docs/@<branch>), which forcesreviewers to navigate to the page they actually changed. This makes
the comment deep-link to the first added, modified, or renamed
Markdown page under
docs/instead.If a PR only deletes Markdown files (or only changes non-Markdown
files such as images or
manifest.json), the workflow now exitswithout commenting.
How the page is selected
No AI/LLM is involved. The workflow uses a deterministic shell
pipeline:
gh api repos/${REPO}/pulls/${PR_NUMBER}/filesto list changedfiles with their
statusandfilename.jqfilterselect(.status != "removed")to drop deletions.grep -E '^docs/.*\.md$' | head -n 1to keep the first Markdownfile under
docs/.caseblock maps that repo path to a docs-site URLsuffix.
gh pr commentposts the rendered URL.Path mapping
docs/README.mddocs/install/index.md/installdocs/ai-coder/tasks.md/ai-coder/tasksdocs/about/contributing/CONTRIBUTING.md/about/contributing/CONTRIBUTINGProof
Re-running the new logic against #24831
(which only modifies
docs/ai-coder/tasks.md) produces:Versus today's link, which lands on the docs index for the branch:
A unit-style smoke test of the path-mapping shell logic was run
locally and all cases pass:
Local test output
actionlint(with shellcheck integration) is clean.Note
AI-assisted: this PR was authored by Coder Agents on @david-fraley's
behalf, per
AI_CONTRIBUTING.md.