mirror of
https://github.com/coder/coder.git
synced 2026-06-02 20:48:20 +00:00
Nick Vigilante
e32fdc813b
Fixes DOCS-174: the docs-preview workflow only fired on `pull_request: opened`. Subsequent pushes left the preview comment stale. ## Changes - Add `synchronize` and `reopened` to trigger types so subsequent pushes retrigger the workflow. - Add a workflow-level `concurrency` group keyed by PR number with `cancel-in-progress: true` so rapid successive pushes don't race the comment-upsert lookup. - Replace always-create comment logic with an upsert: find the existing comment containing `<!-- docs-preview -->` and PATCH it; fall through to create only when none exists or the PATCH itself fails (comment was deleted between find and update). - Filter the upsert lookup to comments authored by `github-actions[bot]` so a human comment containing the marker is never silently overwritten. - Decouple the `gh api` lookup from the `head -n 1` pipe so API failures (network, auth, rate-limit) propagate immediately instead of being swallowed by `|| true`. - Delete the stale preview comment when a `synchronize` push drops all Markdown changes (e.g. a follow-up push that removes the file an earlier push had previewed but still touches `docs/`). The previous preview comment would otherwise point at a deleted page. - Extract the marker and the comment-selector jq into a single `DOCS_PREVIEW_MARKER` variable and a `list_docs_preview_comments` shell function so the stale-cleanup and upsert branches share one source of truth. ## Out of scope Vercel ISR cache invalidation for feature branch previews requires a coder.com change (the `algolia-docs-sync` endpoint only accepts `main` and `release/*` refs). Tracked separately in DOCS-174 out-of-scope notes. Pulls that fully revert their `docs/` changes in a follow-up push won't fire this workflow at all (GitHub's `paths` filter requires a path match in the diff), so a stale preview comment can survive on that specific edge. Removing the `paths` filter to handle it would run the workflow on every PR push, which is disproportionate. Acknowledged in [CRF-12](https://github.com/coder/coder/pull/25456#discussion_r3313738550). <details> <summary>Implementation notes</summary> **Marker and selector deduplication**: The marker string and jq selector previously appeared at three sites (comment body, stale-cleanup API call, upsert API call). They're now consolidated into `DOCS_PREVIEW_MARKER` plus a `list_docs_preview_comments` shell function so a future marker change updates one place. **Comment body construction**: The double-quoted multi-line string form with escaped backticks (`` \` ``) for the inline-code spans is shellcheck-clean. An earlier draft used `printf -v comment_body` with a single-quoted format string containing backticks, which triggered SC2016; the printf-three-pieces workaround that replaced it has since been simplified to the direct double-quoted form. **Upsert logic**: `gh api --paginate` fetches all PR comments, jq filters to `github-actions[bot]`-authored comments containing the marker, and the workflow PATCHes the first match. If the PATCH fails (404 because the comment was deleted between find and update), the script falls through to `gh pr comment` to create a new one. Self-heals on the next push if both paths somehow fail. **Stale-cleanup logic**: Same selector as upsert, but in the early-exit branch when no Markdown files exist in this push. `DELETE` failures are logged and execution continues (the next push will re-attempt or post a fresh comment), so a transient API failure won't fail the CI job. </details> > Generated by Coder Agents on behalf of @nickvigilante