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
*Disclaimer: implemented by a Coder Agent using Claude Opus 4.*
---
Move `github.repository` from direct `${{ }}` interpolation in the
`run:`
block to an `env:` var, consistent with how `BRANCH` and `PR_NUMBER` are
already handled. This eliminates a `zizmor` template-injection finding.
Follows up on #24283.
*Disclaimer: implemented by a Coder Agent using Claude Opus 4.6*
---
Adds a lightweight workflow that posts a docs preview link as a PR
comment
whenever a pull request touches files under `docs/`. The preview is
served
by coder.com's branch-preview feature at `/docs/@<branch>`.
The branch name is URL-encoded so names with slashes (e.g.
`user/feature`) produce correct links like
`/docs/@user%2Ffeature` instead of broken paths.
The comment is created on open and updated in-place on subsequent pushes
using the `peter-evans/find-comment` + `create-or-update-comment`
pattern
already used by the `pr-deploy` workflow.
---
Depends on https://github.com/coder/coder.com/pull/708
Nick Vigilante