# This workflow posts a docs preview comment listing every navigable

# page a pull request touches. The preview is served by coder.com's

# branch-preview feature at /docs/@<branch>.

#

# Each page in the list gets its own preview link plus a Markdown

# task-list checkbox, so a reviewer can tick off pages as they review

# them. State is round-tripped across pushes: a checkbox a reviewer

# already ticked stays ticked as long as that page hasn't changed

# since, but flips back to unchecked the moment new content lands on

# that page, since a checked box should mean "I've reviewed the

# current revision," not "I reviewed some earlier revision of this

# page."

#

# The checkbox contract (reset-on-change) matches GitHub's native

# per-file "Viewed" control, but Viewed tracks the raw diff and can't

# deep-link to the rendered coder.com preview. This checklist tracks

# review of the preview page itself, which the platform doesn't

# provide, so the state is reimplemented here rather than reused.

#

# Only pages that resolve to a route in docs/manifest.json get a

# link. Anything else (docs/.style/** contributor tooling, or a page

# that hasn't been wired into navigation yet) is dropped from the list

# entirely, since those pages 404 on the docs site and would confuse

# reviewers.

#

# Branch names are URL-encoded so that names containing slashes or

# other special characters produce working links.

#

# On subsequent pushes (synchronize) the existing comment is updated

# rather than creating a duplicate. If a previous push had eligible

# Markdown files but the current push has none, the stale comment is

# deleted so readers don't follow a dead deep-link. If the PR only

# deletes Markdown files (or only changes non-Markdown files such as

# images or manifest.json), no comment is posted.

name: docs-preview

on:

pull_request:

types:

- opened

- synchronize

- reopened

paths:

- "docs/**"

# docs/.style/** is contributor tooling and never deploys to coder.com.

# Skipping the workflow on .style-only PRs avoids posting a preview

# comment with an empty page list. Mixed PRs still trigger; the

# selection logic below filters .style files out of the preview list.

- "!docs/.style/**"

concurrency:

group: docs-preview-${{ github.event.pull_request.number }}

cancel-in-progress: true

permissions:

contents: read

jobs:

docs-preview:

runs-on: ubuntu-latest

permissions:

# Job-level permissions replace (not merge with) the workflow-level

# defaults above, so contents: read has to be repeated here for the

# docs/manifest.json contents-API read below.

contents: read

pull-requests: write # needed for commenting on PRs

steps:

- name: Post docs preview comment

env:

GH_TOKEN: ${{ github.token }}

BRANCH: ${{ github.event.pull_request.head.ref }}

HEAD_SHA: ${{ github.event.pull_request.head.sha }}

PR_NUMBER: ${{ github.event.pull_request.number }}

REPO: ${{ github.repository }}

run: |

set -euo pipefail

# DOCS_PREVIEW_MARKER locates this workflow's own comments.

# STATE_PREFIX carries the last-seen `path -> blob sha` map for

# change detection. Keep this script's map_doc_path, manifest

# filter, and carryover logic in sync with

# test-docs-preview-mapper.sh.

DOCS_PREVIEW_MARKER='<!-- docs-preview -->'

STATE_PREFIX='docs-preview-state:'

# Returns IDs of github-actions[bot] comments on the PR whose

# body contains DOCS_PREVIEW_MARKER.

list_docs_preview_comments() {

gh api --paginate \

"repos/${REPO}/issues/${PR_NUMBER}/comments" \

--jq ".[] | select(.user.login == \"github-actions[bot]\") | select(.body | contains(\"${DOCS_PREVIEW_MARKER}\")) | .id"

}

# Deletes the existing docs-preview comment (found earlier as

# existing_id) and exits 0, so a stale comment doesn't point

# readers at a dead deep-link. A failed delete is only cosmetic,

# so it logs and exits clean; the next push retries. The upsert

# path uses strict propagation instead, since silent failure

# there would duplicate comments.

cleanup_stale_and_exit() {

if [ -n "$existing_id" ]; then

if gh api --method DELETE \

"repos/${REPO}/issues/comments/${existing_id}"; then

echo "Deleted stale docs preview comment (id=${existing_id})."

else

echo "Failed to delete stale docs preview comment (id=${existing_id}); leaving in place. This is usually a transient API error, and the next push retries the cleanup." >&2

fi

fi

exit 0

}

# Maps a repo path to the docs site URL path.

# docs/README.md -> "" (docs root)

# docs/<dir>/index.md -> "<dir>" (directory index)

# docs/<dir>/README.md -> "<dir>" (directory index)

# docs/<dir>/<file>.md -> "<dir>/<file>"

map_doc_path() {

local doc_path="$1"

local rel="${doc_path#docs/}"

local page_path

case "$rel" in

README.md)

page_path=""

;;

*)

local base dir stripped

base="$(basename "$rel")"

dir="$(dirname "$rel")"

if [ "$dir" = "." ]; then

dir=""

fi

case "$base" in

index.md | README.md)

page_path="$dir"

;;

*)

stripped="${base%.md}"

if [ -z "$dir" ]; then

page_path="$stripped"

else

page_path="${dir}/${stripped}"

fi

;;

esac

;;

esac

printf '%s' "$page_path"

}

# Look up the existing docs-preview comment id up front so both

# the cleanup path and the upsert path can reuse it without

# listing twice. The body is fetched later, just before state

# recovery, to keep the read-modify-write window small.

#

# Keep the strict list separate from the tolerant head. A real

# list failure (network, auth, rate-limit) must propagate under

# set -e; otherwise the upsert treats it as "no comment" and

# posts a duplicate. The `|| true` only absorbs head's SIGPIPE

# on the printf feeding head.

all_comment_ids=$(list_docs_preview_comments)

existing_id=$(printf '%s\n' "$all_comment_ids" | head -n 1) || true

# Fetch the non-removed Markdown files under docs/ (excluding

# docs/.style/**) this PR currently touches, one <filename>\t<sha>

# pair per line. `.sha` is the blob sha of the file's content at

# this push, which is what lets later runs detect "this page

# changed since it was last listed" without a full checkout.

#

# This is intentionally not piped into grep so that a gh-api

# failure (network, auth, rate-limit) propagates immediately

# instead of being swallowed by `|| true`.

#

# `pulls/files` truncates at GitHub's 3000-file ceiling, which

# --paginate does not lift. A PR that changes 3000+ files would

# list only the first 3000; docs PRs never approach that.

changed_tsv=$(gh api --paginate \

"repos/${REPO}/pulls/${PR_NUMBER}/files" \

--jq '.[] | select(.status != "removed") | select(.filename | test("^docs/.*\\.md$")) | select((.filename | test("^docs/\\.style/")) | not) | [.filename, .sha] | @tsv')

if [ -z "$changed_tsv" ]; then

echo "No added/modified Markdown files under docs/ (outside docs/.style/) on this push."

cleanup_stale_and_exit

fi

# Fetch docs/manifest.json at the PR head sha (this job never

# checks the repo out) and collect every object with a "path"

# key, which in the manifest is always a navigable page entry.

# Manifest paths are written "./foo/bar.md" or "foo/bar.md"

# relative to docs/; normalize both to "docs/foo/bar.md" so

# they compare directly against the PR-files filenames above.

#

# Request the raw blob rather than the JSON envelope so the

# read has no 1MB inline-body ceiling, which would otherwise

# return an empty body and silently drop every page.

#

# This makes the manifest an implicit hard dependency of comment

# persistence: if the manifest schema ever drops or renames the

# "path" key, the fetch still succeeds but allowed_paths comes

# back empty, no page is eligible, and the run takes

# cleanup_stale_and_exit, deleting the comment and its checkbox

# state. "Parsed fine, zero matches" is indistinguishable from

# "format changed," so a future manifest refactor must keep this

# extraction in step.

manifest_content=$(gh api -H "Accept: application/vnd.github.raw" "repos/${REPO}/contents/docs/manifest.json?ref=${HEAD_SHA}")

allowed_paths=$(printf '%s' "$manifest_content" \

| jq -r '[.. | objects | select(has("path")) | .path] | .[]' \

| sed -E 's#^\./##; s#^#docs/#')

# Intersect the changed-files set with the manifest allowlist.

# A file with no manifest route 404s on the docs site, so drop

# it from the list rather than link to a broken preview.

eligible_tsv=$(printf '%s\n' "$changed_tsv" | while IFS=$'\t' read -r filename sha; do

[ -z "$filename" ] && continue

if printf '%s\n' "$allowed_paths" | grep -qxF "$filename"; then

printf '%s\t%s\n' "$filename" "$sha"

fi

done)

if [ -z "$eligible_tsv" ]; then

echo "No changed Markdown files resolve to a docs/manifest.json route."

echo "(If pages you expect are missing, check docs/manifest.json's schema: an empty allowlist looks identical to no eligible pages.)"

cleanup_stale_and_exit

fi

eligible_json=$(printf '%s\n' "$eligible_tsv" \

| jq -R -s '[splits("\n") | select(length > 0) | split("\t") | {filename: .[0], sha: .[1]}]')

# Fetch the existing comment body now, right before reading its

# checkbox state, so a reviewer's toggle isn't overwritten by a

# stale read taken several API calls earlier. `|| true` keeps a

# transient API error from failing the run; state recovery then

# just treats every page as new.

#

# A reviewer toggle that lands in the small window between this

# read and the PATCH below is lost, but reappears correctly on

# the next push. Accepted limitation, not a bug.

existing_body=""

if [ -n "$existing_id" ]; then

existing_body=$(gh api "repos/${REPO}/issues/comments/${existing_id}" --jq '.body' || true)

if [ -z "$existing_body" ]; then

# A docs-preview comment always contains its body, so an

# empty read against a known id is a transient fetch

# failure, not a legitimately empty comment. State recovery

# will reset every checkbox this push; log a breadcrumb so

# the reset isn't silent (it self-heals on the next push).

echo "Could not read existing comment ${existing_id}; checkbox state resets this push (transient, self-heals)." >&2

fi

fi

# Recover state from the existing comment, if any:

# - old_state: the path -> sha map this workflow wrote the

# last time it updated the comment (hidden marker).

# - old_checked: the path -> checked map read from the

# *live* checkbox glyphs in the comment body, which is

# where a reviewer's manual clicks land (GitHub persists a

# checkbox toggle as an edit to the comment body).

old_state_json="{}"

old_checked_json="{}"

if [ -n "$existing_body" ]; then

old_state_b64=$(printf '%s\n' "$existing_body" | grep -oE "${STATE_PREFIX}[A-Za-z0-9+/=]+" | sed "s/^${STATE_PREFIX}//") || true

if [ -n "$old_state_b64" ]; then

# Guard the decode: a truncated or corrupted marker must

# degrade to "treat every page as new", not kill the run

# (base64 -d and jq both run under set -e). Reject an empty

# decode before the type check: on jq < 1.7 `jq -e` exits 0

# on empty input, so the type check alone would accept an

# empty string and `--argjson old_state ""` would abort the

# run. Require a non-empty result that parses as a JSON

# object, else keep {}.

decoded=$(printf '%s' "$old_state_b64" | base64 -d 2>/dev/null || true)

if [ -n "$decoded" ] && printf '%s' "$decoded" | jq -e 'type == "object"' >/dev/null 2>&1; then

old_state_json="$decoded"

fi

fi

# shellcheck disable=SC2016 # backticks below are literal Markdown code-span delimiters, not command substitution.

old_checked_json=$(printf '%s\n' "$existing_body" \

| grep -oE '^[[:space:]]*- \[[ xX]\] \[`[^`]+`\]' \

| sed -E 's/^[[:space:]]*- \[([ xX])\] \[`([^`]+)`\]/\1\t\2/' \

| jq -R -s '[splits("\n") | select(length > 0) | split("\t") | {(.[1]): (.[0] | test("x"; "i"))}] | add // {}') || true

fi

# Decide each page's checked state: carry the live checkbox

# value forward only if the page's blob sha hasn't changed

# since the last time this workflow wrote the state marker.

# New pages, and pages whose sha moved, start unchecked.

final_rows=$(jq -n \

--argjson eligible "$eligible_json" \

--argjson old_state "$old_state_json" \

--argjson old_checked "$old_checked_json" \

'[

$eligible[] | . as $f |

($old_state[$f.filename] // null) as $prev_sha |

(if $prev_sha != null and $prev_sha == $f.sha

then ($old_checked[$f.filename] // false)

else false

end) as $checked |

{filename: $f.filename, sha: $f.sha, checked: $checked}

] | sort_by(.filename)')

# URL-encode the branch name so slashes and special

# characters don't break the preview URL. The page path is

# left as-is because its components are simple ASCII path

# segments and the slashes between them must be preserved.

encoded_branch=$(jq -rn --arg b "$BRANCH" '$b | @uri')

url_prefix="https://coder.com/docs/@${encoded_branch}"

total_pages=$(printf '%s' "$final_rows" | jq 'length')

# Assemble the comment body for the first N pages: the checklist,

# the hidden base64 state marker, and (when N < total_pages) the

# omitted-pages summary line. Both the checklist and the marker

# derive from the same N rows, so this prints exactly the bytes

# that get posted, which is what lets the caller size the comment

# by measuring rather than estimating.

build_comment_body() {

local n="$1" rows state_json state_b64 checklist="" intro

local filename checked page_path url box omitted

rows=$(printf '%s' "$final_rows" | jq -c --argjson n "$n" '.[:$n]')

state_json=$(printf '%s' "$rows" | jq -c 'map({(.filename): .sha}) | add // {}')

state_b64=$(printf '%s' "$state_json" | base64 -w0)

while IFS=$'\t' read -r filename checked; do

[ -z "$filename" ] && continue

page_path=$(map_doc_path "$filename")

url="$url_prefix"

if [ -n "$page_path" ]; then

url="${url}/${page_path}"

fi

box=" "

if [ "$checked" = "true" ]; then

box="x"

fi

# The backticks are literal Markdown code-span delimiters.

checklist="${checklist}- [${box}] [\`${filename}\`](${url})"$'\n'

done < <(printf '%s' "$rows" | jq -r '.[] | [.filename, (.checked | tostring)] | @tsv')

omitted=$((total_pages - n))

if [ "$omitted" -gt 0 ]; then

checklist="${checklist}"$'\n'"_and ${omitted} more changed page(s) not listed to stay under GitHub's comment size limit. See the [Files tab](https://github.com/${REPO}/pull/${PR_NUMBER}/files) for the full list._"$'\n'

fi

intro="Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here."

printf '## Docs preview\n\n%s\n\n%s\n%s\n<!-- %s%s -->' \

"$intro" "$checklist" "$DOCS_PREVIEW_MARKER" "$STATE_PREFIX" "$state_b64"

}

# GitHub caps a comment body at 65536 characters. Estimating the

# per-page cost drifts from the real size (each page adds a

# checklist line and a base64 state entry whose combined length

# depends on the path), so assemble the real body and measure it

# instead. Keep every page if they all fit; otherwise binary

# search for the largest leading prefix that stays under budget.

# Body size grows monotonically with the page count, so the

# search is well defined. 65000 leaves headroom under the limit.

comment_budget=65000

body_bytes() { LC_ALL=C wc -c; }

if [ "$(build_comment_body "$total_pages" | body_bytes)" -le "$comment_budget" ]; then

keep_pages=$total_pages

else

lo=0

hi=$((total_pages - 1))

keep_pages=0

while [ "$lo" -le "$hi" ]; do

mid=$(((lo + hi) / 2))

if [ "$(build_comment_body "$mid" | body_bytes)" -le "$comment_budget" ]; then

keep_pages=$mid

lo=$((mid + 1))

else

hi=$((mid - 1))

fi

done

fi

# Always list at least one page. The binary search can floor at

# 0 only if a single line exceeds the budget (impossible at real

# path lengths), and an empty list under an "and N more" summary

# would be self-contradicting; a floor of 1 makes that

# unreachable state impossible.

if [ "$keep_pages" -lt 1 ]; then

keep_pages=1

fi

omitted_pages=$((total_pages - keep_pages))

echo "Listing ${keep_pages} of ${total_pages} changed page(s); ${omitted_pages} omitted for comment size."

comment_body=$(build_comment_body "$keep_pages")

# Upsert: PATCH the existing comment if we found one, else

# create it. existing_id is re-derived from a live list on

# every run (never persisted), so a genuinely deleted comment

# isn't found and lands in the create branch below.

#

# Therefore a PATCH failure against a known existing_id almost

# always means the comment still exists and the error is

# transient: never create in that case, or we post a permanent

# duplicate (the write-path sibling of the guarded list

# failure). Fail instead; the next push retries.

if [ -n "$existing_id" ]; then

if gh api --method PATCH \

"repos/${REPO}/issues/comments/${existing_id}" \

--raw-field body="$comment_body"; then

echo "Updated existing docs preview comment (id=${existing_id})."

else

echo "Failed to update docs preview comment ${existing_id}; leaving it in place to avoid a duplicate. This is usually a transient API error, and the next push will retry." >&2

exit 1

fi

else

gh pr comment "${PR_NUMBER}" \

--repo "${REPO}" \

--body "$comment_body"

echo "Created new docs preview comment."

fi