Thanks to visit codestin.com
Credit goes to github.com

Skip to content
Update coder.com/docs

docs: retire the generated feature stage lists (#29113) #596

Sign in to view logs

docs: retire the generated feature stage lists (#29113)

docs: retire the generated feature stage lists (#29113) #596

Workflow file for this run

.github/workflows/deploy-docs.yaml at b23d73d
name: Update coder.com/docs
# Triggers updates to the public docs at coder.com/docs from three
# sources:
#
# * push to main or release/* (docs/** only): markdown edits land in
# search and ISR within seconds.
# * release.published: when a stable vX.Y.Z release ships on this
# repo, the workflow translates the tag to its release/X.Y branch
# and reindexes. Eliminates the manual workflow_dispatch step from
# the mainline rotation. Prereleases and non-semver tags are
# skipped. See DOCS-327.
# * workflow_dispatch: operator-driven, with explicit action and ref.
#
# One preflight job (`changes`) feeds two parallel sibling jobs so that
# search records, the static cache, and any new routes register at the
# same time:
#
# 1. algolia-and-isr: HMAC-signed POST to coder.com/api/algolia-docs-sync.
# The handler re-extracts records for the (corpus, ref) pair and
# atomically replaces the slice of the Algolia `docs` index, then
# calls `res.revalidate(p)` for every navigable manifest entry to
# refresh Vercel's static-page cache without a full rebuild. Runs
# on every docs/** push.
#
# 2. vercel-rebuild: fires the Vercel deploy hook for a full
# build+deploy. Only runs when docs/manifest.json changed, since a
# manifest change can introduce or remove routes that Next.js's
# `getStaticPaths` only re-evaluates on a full rebuild.
#
# Markdown-only edits hit only path 1 and surface in seconds. Manifest
# edits hit both paths in parallel; the ISR revalidate is harmless
# against the previous deployment while the new build is in flight,
# and Vercel only swaps to the new build atomically when ready.
#
# https://vercel.com/docs/deploy-hooks#triggering-a-deploy-hook
# See coder/coder.com/src/pages/api/algolia-docs-sync.ts.
on:
push:
branches:
- main
- "release/*"
paths:
# Intentionally only docs/**. Edits to this workflow file must not
# auto-trigger a production reindex; use workflow_dispatch instead.
# See DOCS-121 (incident) and DOCS-124 (fix).
#
# docs/.style/** is contributor tooling and never deploys to
# coder.com/docs. Negating it here skips the workflow on .style-only
# commits. GitHub Actions only suppresses when every changed file
# matches a negation, so mixed commits still trigger; the surgical
# diff step below drops .style paths from the payload.
- "docs/**"
- "!docs/.style/**"
release:
# Fires when a draft release is published, when a release goes from
# prerelease to non-prerelease, or when a release is created already
# published. The Compute step below translates the published tag
# (vX.Y.Z) into its release/X.Y branch and skips prereleases. See
# DOCS-327 for the rotation context that motivated this trigger.
types: [published]
workflow_dispatch:
inputs:
action:
description: "Algolia action to perform"
required: true
type: choice
default: index
options:
- index
- delete
ref:
description: "Branch to (re)index or delete (e.g. main, release/2.32). Defaults to the workflow's checkout ref."
required: false
type: string
permissions:
contents: read
# Do not cancel in-progress runs. Each run's `changes` job diffs the
# event's own (before, after) SHA pair, so two rapid pushes produce two
# non-overlapping surgical-mode requests. Cancelling the first run
# would silently drop its diff: the second run only sees its own pair,
# never sees the cancelled run's paths, and the dropped pages would
# stay stale until the next whole-branch reindex (manifest change,
# >50-file push, or manual workflow_dispatch). Runs are lightweight
# (shell + curl, ~2 minutes), so overlapping runs are cheap.
concurrency:
group: deploy-docs-${{ github.ref }}
cancel-in-progress: false
jobs:
# Detect what changed so the dependent jobs know:
# - whether a Vercel full rebuild is needed (manifest changed), and
# - which markdown pages to surgically reindex (the changed set).
#
# Outputs:
# manifest_changed: "true" | "false"
# paths_json: a JSON array of {path, status} objects, or "[]"
# when no markdown changes are eligible for
# surgical mode (manifest-only push, an
# uncomputable diff, a non-push event
# (workflow_dispatch or release.published),
# or a diff that exceeds the surgical-mode cap).
# An empty array tells the handler to fall back
# to whole-branch reindex.
changes:
runs-on: ubuntu-latest
outputs:
manifest_changed: ${{ steps.diff.outputs.manifest_changed }}
paths_json: ${{ steps.diff.outputs.paths_json }}
steps:
- name: Compute changed-files signal
id: diff
env:
EVENT_NAME: ${{ github.event_name }}
BEFORE_SHA: ${{ github.event.before }}
AFTER_SHA: ${{ github.sha }}
run: |
set -euo pipefail
emit_whole_branch_fallback() {
# Tells the algolia-and-isr job to operate in whole-branch
# mode by sending an empty paths array. The handler treats
# the absence of paths (or an empty list) as "reindex
# everything for this (corpus, ref)".
echo "paths_json=[]" >> "$GITHUB_OUTPUT"
}
# Non-push events (workflow_dispatch, release.published)
# have no diff range; treat as "manifest unchanged" so the
# manual or release-triggered reindex doesn't fire a Vercel
# rebuild it didn't ask for, and as whole-branch so the
# resulting reindex is exhaustive.
if [ "$EVENT_NAME" != "push" ]; then
echo "manifest_changed=false" >> "$GITHUB_OUTPUT"
emit_whole_branch_fallback
exit 0
fi
# First push to a brand-new branch has BEFORE_SHA = all zeros.
# In that edge case we conservatively assume the manifest is
# part of the initial state and trigger a full rebuild + a
# whole-branch reindex.
if [ -z "${BEFORE_SHA:-}" ] || [ "$BEFORE_SHA" = "0000000000000000000000000000000000000000" ]; then
echo "manifest_changed=true" >> "$GITHUB_OUTPUT"
emit_whole_branch_fallback
exit 0
fi
# We don't need a full checkout for `git diff` against two
# known SHAs. A shallow fetch of just those two commits is
# enough.
git init -q
git remote add origin "https://github.com/${GITHUB_REPOSITORY}.git"
GIT_ERR=$(mktemp)
if ! git -c protocol.version=2 fetch --depth=1 origin "$BEFORE_SHA" "$AFTER_SHA" 2>"$GIT_ERR"; then
# Fall back to whole-branch if the shallow fetch failed
# (e.g. force-push rewrote history). Surfacing the git
# stderr line in the warning lets operators diagnose
# network or auth failures without reproducing the fetch
# manually.
FIRST_ERR=$(head -1 "$GIT_ERR" 2>/dev/null || true)
echo "::warning::Could not fetch BEFORE_SHA=$BEFORE_SHA: ${FIRST_ERR:-unknown}; assuming manifest changed"
echo "manifest_changed=true" >> "$GITHUB_OUTPUT"
emit_whole_branch_fallback
exit 0
fi
# Manifest signal.
if git diff --name-only "$BEFORE_SHA" "$AFTER_SHA" -- docs/manifest.json | grep -q .; then
echo "manifest_changed=true" >> "$GITHUB_OUTPUT"
# Manifest changes can rename or restructure routes, so
# surgical mode is not safe; a per-path delete keyed off
# the new canonical URL would miss records under old URLs.
# Whole-branch reindex is the right behavior here.
emit_whole_branch_fallback
exit 0
else
echo "manifest_changed=false" >> "$GITHUB_OUTPUT"
fi
# Surgical mode: emit the changed markdown set as a JSON
# array of {path, status} objects. We use --name-status -z
# so the handler can distinguish modified/added (re-extract
# + save) from deleted/renamed-old-side (delete only), and
# so paths containing whitespace or quotes survive intact.
DIFF_FILE=$(mktemp)
# 'docs/**/*.md' to keep markdown-only paths, ':(exclude)docs/.style/**'
# so contributor-tooling pages never reach the surgical-reindex payload
# on mixed commits. The trigger filter already short-circuits .style-only
# pushes; this is defense in depth.
git diff --name-status -z "$BEFORE_SHA" "$AFTER_SHA" -- 'docs/**/*.md' ':(exclude)docs/.style/**' > "$DIFF_FILE"
# Parse the NUL-delimited diff into <path>\t<status> lines.
# `--name-status -z` uses NUL between fields and between
# records, with a special twist for renames: the record is
# `R<n>\0<old>\0<new>\0`, three NUL-delimited fields instead
# of two. Status codes: A=added, M=modified, T=type-changed
# (treated as modified), D=deleted, R<n>=renamed (we index
# the new path since that is the live route). Unknown codes
# log a warning and are skipped; a single awk handles both
# the parsing and the count so the two cannot disagree.
#
# Tested in test-deploy-docs-diff.sh. Keep that script in
# sync with any changes to this block.
PARSED=$(mktemp)
awk -v RS='\0' '
function emit(path, status) {
printf "%s\t%s\n", path, status
}
{
code = substr($0, 1, 1)
if (code == "A") { getline; emit($0, "added"); next }
if (code == "M") { getline; emit($0, "modified"); next }
if (code == "T") { getline; emit($0, "modified"); next }
if (code == "D") { getline; emit($0, "deleted"); next }
if (code == "R") {
# R<similarity>\0<old>\0<new>\0
getline old_path
getline new_path
emit(new_path, "renamed")
next
}
if ($0 != "") {
# Unknown status code. Consume the path field so the
# record alignment stays correct, then warn.
unknown_code = $0
getline unknown_path
printf "::warning::Unknown git diff status %s for %s; skipping.\n", unknown_code, unknown_path > "/dev/stderr"
}
}
' "$DIFF_FILE" > "$PARSED"
# Count is derived from the emitter output, so the count and
# the JSON payload cannot diverge by construction (DEREM-21).
CHANGED=$(wc -l < "$PARSED" | tr -d ' ')
if [ "$CHANGED" -eq 0 ]; then
# Markdown-only path filter on the trigger means we should
# only get here on edits to non-markdown files under docs/
# (e.g., images). Whole-branch reindex is overkill for
# those, but it is also harmless and avoids a special case;
# an empty paths array makes the handler skip both the
# save and the revalidate when no manifest entry maps to
# the changed file.
emit_whole_branch_fallback
exit 0
fi
# Cap at 50 changed files. Above that a whole-branch reindex
# is faster (one deleteBy + one saveObjects vs N deleteBy
# calls), and the surgical-mode payload also stays well under
# GitHub Actions' output size limit.
if [ "$CHANGED" -gt 50 ]; then
echo "::notice::$CHANGED markdown files changed; falling back to whole-branch reindex (cap is 50 for surgical mode)"
emit_whole_branch_fallback
exit 0
fi
# jq -Rcn slurps the <path>\t<status> lines and handles JSON
# escaping for quotes, backslashes, and any other special
# characters in the path.
PATHS_JSON=$(jq -Rcn '
[ inputs
| split("\t")
| { path: .[0], status: .[1] }
]
' < "$PARSED")
# Defense in depth: fail loudly if jq could not parse what
# we built. jq -c already validates structure; this catches
# the empty-stdin edge case.
if [ -z "$PATHS_JSON" ] || [ "$PATHS_JSON" = "null" ]; then
PATHS_JSON='[]'
fi
echo "paths_json=$PATHS_JSON" >> "$GITHUB_OUTPUT"
echo "Surgical mode: $CHANGED path(s) changed."
# Path 1: always run. Notifies coder.com to refresh Algolia records
# and ISR-revalidate the affected pages.
algolia-and-isr:
runs-on: ubuntu-latest
needs: changes
steps:
- name: Compute action and ref
id: input
env:
INPUT_ACTION: ${{ inputs.action }}
INPUT_REF: ${{ inputs.ref }}
GITHUB_REF_NAME: ${{ github.ref_name }}
EVENT_NAME: ${{ github.event_name }}
RELEASE_TAG: ${{ github.event.release.tag_name }}
RELEASE_PRERELEASE: ${{ github.event.release.prerelease }}
run: |
set -euo pipefail
ACTION=""
REF=""
# release.published path: translate a stable vX.Y.Z tag into
# its release/X.Y branch and let the rest of the step
# validate. Skip prereleases and any tag that does not match
# the plain semver shape; backports (vX.Y.<patch>) are
# in-scope because they may carry doc updates worth
# reindexing. See DOCS-327. The handler's allowlist gates the
# downstream POST, so an unsupported minor still no-ops
# rather than reindexing something we did not intend.
#
# Tested in test-deploy-docs-release.sh. Keep that script in
# sync with any changes to this block.
if [ "${EVENT_NAME:-}" = "release" ]; then
if [ "${RELEASE_PRERELEASE:-false}" = "true" ]; then
echo "::notice::Skipping prerelease ${RELEASE_TAG:-<unknown>}; no docs reindex."
exit 0
fi
if [[ "${RELEASE_TAG:-}" =~ ^v([0-9]+)\.([0-9]+)\.[0-9]+$ ]]; then
ACTION="index"
REF="release/${BASH_REMATCH[1]}.${BASH_REMATCH[2]}"
echo "::notice::Release ${RELEASE_TAG} resolved to ref ${REF}."
else
echo "::notice::Skipping ${RELEASE_TAG:-<unknown>}: not a plain vX.Y.Z release tag."
exit 0
fi
fi
ACTION="${ACTION:-${INPUT_ACTION:-index}}"
REF="${REF:-${INPUT_REF:-$GITHUB_REF_NAME}}"
# Reject newlines/carriage returns in either input. GitHub
# Actions parses GITHUB_OUTPUT line-by-line with last-writer-
# wins, so a newline in $REF would let an operator dispatch
# `release/x\naction=delete\nref=main` past the validation
# below (the case `*` glob matches the multi-line string),
# then have `echo "ref=$REF" >> $GITHUB_OUTPUT` write three
# lines whose effective outputs are `action=delete ref=main`.
# `inputs.ref` is a single-line UI field; the REST API will
# accept anything. Reject embedded newlines explicitly.
case "$ACTION" in
*[$'\n\r']*)
echo "::error::action must not contain newlines."
exit 1
;;
esac
case "$REF" in
*[$'\n\r']*)
echo "::error::ref must not contain newlines."
exit 1
;;
esac
# The workflow_dispatch `type: choice` is enforced only by
# the GitHub UI. The REST API will accept any string. We
# validate explicitly so a malformed action never reaches
# the handler (which trusts this value after HMAC check).
case "$ACTION" in
index|delete) ;;
*)
echo "::error::Unsupported action '$ACTION'. Must be 'index' or 'delete'."
exit 1
;;
esac
case "$REF" in
main|release/*) ;;
*)
echo "::error::Unsupported ref '$REF'. Only main and release/* are eligible."
exit 1
;;
esac
# Refuse to run `action=delete` against main. The dispatch
# UI defaults `ref` to the dispatching branch (typically
# `main`), so a single forgotten field when cleaning up a
# release branch would wipe production search records.
# Force the operator to type the ref explicitly for delete.
if [ "$ACTION" = "delete" ] && [ "$REF" = "main" ]; then
echo "::error::Refusing to delete records for ref=main. Specify a release/* ref explicitly when dispatching delete."
exit 1
fi
echo "action=$ACTION" >> "$GITHUB_OUTPUT"
echo "ref=$REF" >> "$GITHUB_OUTPUT"
- name: POST to coder.com docs indexer
# Sentinel guard. The Compute step has two release-event
# early-exit paths (prerelease skip, non-semver tag skip) that
# succeed without writing action/ref to GITHUB_OUTPUT. Without
# this guard, the POST would still fire with empty ACTION and
# REF env vars, sending stray no-op traffic to the production
# handler. The step only writes `action` on the success path,
# so its presence is a reliable proceed signal. See DOCS-327.
if: steps.input.outputs.action != ''
env:
ACTION: ${{ steps.input.outputs.action }}
REF: ${{ steps.input.outputs.ref }}
PATHS_JSON: ${{ needs.changes.outputs.paths_json }}
SECRET: ${{ secrets.ALGOLIA_DOCS_SYNC_SECRET }}
run: |
set -euo pipefail
if [ -z "${SECRET:-}" ]; then
echo "::error::ALGOLIA_DOCS_SYNC_SECRET is not configured."
exit 1
fi
# Build the webhook body. paths_json is always a valid JSON
# array (possibly empty) thanks to the changes job. An empty
# array tells the handler to do a whole-branch reindex; a
# non-empty array triggers surgical per-page mode.
if [ -z "${PATHS_JSON:-}" ]; then
PATHS_JSON='[]'
fi
BODY=$(jq -nc \
--arg action "$ACTION" \
--arg corpus "v2" \
--arg ref "$REF" \
--argjson paths "$PATHS_JSON" \
'{action: $action, corpus: $corpus, ref: $ref, paths: $paths}')
# SHA-256 HMAC over the exact bytes we POST. The handler verifies
# with crypto.timingSafeEqual on the same raw body, so the
# prefix and hex casing must match.
SIG="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')"
PATHS_COUNT=$(printf '%s' "$PATHS_JSON" | jq 'length')
MODE="whole-branch"
if [ "$PATHS_COUNT" -gt 0 ]; then
MODE="surgical ($PATHS_COUNT path(s))"
fi
echo "Action: $ACTION Ref: $REF Mode: $MODE"
RESPONSE=$(mktemp)
RC=0
# A whole-branch reindex fetches and extracts a few hundred
# pages server-side and can run past two minutes. Keep
# --max-time in step with the docs indexer's server-side
# function budget so curl waits for the response instead of
# aborting mid-reindex and reporting a false timeout.
HTTP_STATUS=$(curl --fail-with-body -sS \
--connect-timeout 10 \
--max-time 300 \
-o "$RESPONSE" \
-w '%{http_code}' \
-X POST \
-H 'Content-Type: application/json' \
-H "X-Coder-Signature: $SIG" \
--data "$BODY" \
https://coder.com/api/algolia-docs-sync) || RC=$?
# Render only an allowlisted subset of the handler response in
# the step summary. The handler can include free-form fields
# (error, reason, revalidateSampleErrors, skippedReasons,
# recordsByType) that may reflect upstream error strings. This
# repository is public, so the step summary is visible to
# anyone with read access; filter those fields out before the
# summary is written. The full response stays in a temp file and
# is never printed: run logs are public for this repository, so
# the raw body must not reach them either.
#
# Keep this allowlist in sync with SyncResponseBody in
# coder/coder.com/src/pages/api/algolia-docs-sync.ts; add a
# field here only after confirming it is bounded enough to be
# safe for a public UI.
SAFE_RESPONSE=$(jq '
if type == "object" then
{
action,
corpus,
ref,
records,
pagesIndexed,
pagesSkipped,
revalidated,
revalidateFailed,
mode,
pathsRequested,
pathsSkipped,
index,
tookMs
} | with_entries(select(.value != null))
else
{}
end
' "$RESPONSE" 2>/dev/null) || SAFE_RESPONSE='{}'
{
echo "## Algolia + ISR sync"
echo
echo "- Action: \`$ACTION\`"
echo "- Ref: \`$REF\`"
echo "- Mode: \`$MODE\`"
echo "- HTTP status: \`${HTTP_STATUS:-n/a}\`"
echo
echo "### Response (allowlisted fields)"
echo
echo '```json'
printf '%s\n' "$SAFE_RESPONSE"
echo '```'
if [ "$RC" -ne 0 ]; then
echo
echo "### Error"
echo
echo "The request failed. The raw response body is not shown because this repository is public; only the allowlisted fields above and the bounded error code (in the run log) are surfaced."
fi
} >> "$GITHUB_STEP_SUMMARY"
if [ "$RC" -ne 0 ]; then
# This repository is public: run logs and the step summary are
# both world-readable, so surface only the bounded error code,
# never the raw response body. Sanitize the extracted code so the
# "bounded" claim holds literally: `tr -cd` drops anything outside
# [A-Za-z0-9_.-] (removing newlines and `::` so a hostile response
# body can't inject a runner workflow command) and `head -c 64`
# caps the length.
ERR_CODE=$(jq -r '(.error | objects | .code) // empty' "$RESPONSE" 2>/dev/null | tr -cd 'A-Za-z0-9_.-' | head -c 64 || true)
echo "Algolia docs sync request failed: HTTP ${HTTP_STATUS:-n/a}, error code: ${ERR_CODE:-unknown}."
exit "$RC"
fi
# Path 2: full Vercel rebuild. Only fires when docs/manifest.json
# changed, because manifest changes can introduce or remove routes
# that Next.js's `getStaticPaths` only re-evaluates on a full build.
# Markdown-only edits don't need this; ISR revalidate covers them.
vercel-rebuild:
runs-on: ubuntu-latest
needs: changes
if: needs.changes.outputs.manifest_changed == 'true'
steps:
- name: Trigger Vercel deploy hook
env:
HOOK: ${{ secrets.DEPLOY_DOCS_VERCEL_WEBHOOK }}
run: |
set -euo pipefail
if [ -z "${HOOK:-}" ]; then
echo "::error::DEPLOY_DOCS_VERCEL_WEBHOOK is not configured."
exit 1
fi
# Mirror the sibling job's pattern: capture response body and
# HTTP status, write the step summary unconditionally, then
# propagate failure. Without this, set -e would kill the
# script before the summary block on curl failure.
RESPONSE=$(mktemp)
RC=0
HTTP_STATUS=$(curl --fail-with-body -sS \
--connect-timeout 10 \
--max-time 120 \
-o "$RESPONSE" \
-w '%{http_code}' \
-X POST "$HOOK") || RC=$?
# Render only an allowlisted subset of the Vercel deploy hook
# response (job.id, job.state, job.createdAt). The deploy hook
# URL itself is the only secret in this flow; the response
# shape is bounded today, but we filter explicitly to insulate
# the public step summary from any future shape change
# upstream and to keep the two summary blocks consistent.
SAFE_RESPONSE=$(jq '
if type == "object" and (.job | type) == "object" then
{ job: (.job | { id, state, createdAt } | with_entries(select(.value != null))) }
else
{}
end
' "$RESPONSE" 2>/dev/null) || SAFE_RESPONSE='{}'
{
echo "## Vercel rebuild"
echo
echo "- Reason: \`docs/manifest.json\` changed"
echo "- HTTP status: \`${HTTP_STATUS:-n/a}\`"
echo
echo "### Response (allowlisted fields)"
echo
echo '```json'
printf '%s\n' "$SAFE_RESPONSE"
echo '```'
if [ "$RC" -ne 0 ]; then
echo
echo "### Error"
echo
echo "The request failed. The raw response body is not shown because this repository is public; only the allowlisted fields above and the bounded error code (in the run log) are surfaced."
fi
} >> "$GITHUB_STEP_SUMMARY"
if [ "$RC" -ne 0 ]; then
# This repository is public: run logs and the step summary are
# both world-readable, so surface only the bounded error code,
# never the raw response body. Sanitize the extracted code so the
# "bounded" claim holds literally: `tr -cd` drops anything outside
# [A-Za-z0-9_.-] (removing newlines and `::` so a hostile response
# body can't inject a runner workflow command) and `head -c 64`
# caps the length.
ERR_CODE=$(jq -r '(.error | objects | .code) // empty' "$RESPONSE" 2>/dev/null | tr -cd 'A-Za-z0-9_.-' | head -c 64 || true)
echo "Vercel deploy hook request failed: HTTP ${HTTP_STATUS:-n/a}, error code: ${ERR_CODE:-unknown}."
exit "$RC"
fi