docsy(v1): bump infra for the setup-doc refresh (#1566) #854

Workflow file for this run

.github/workflows/build-and-deploy.yml at beeb848

	name: Build and deploy docs

	# Part of the gha-docs-build migration: builds the docs via `make dist`
	# and pushes the result to a Cloudflare Pages project via Direct Upload.
	# Replaces CF Pages' native build runner — CF Pages stays only as the
	# static host.
	#
	# Production-only path (mirrors main). PR previews are handled by the two-stage
	# pair `build-pr.yml` (untrusted build, no secrets) + `deploy-pr-preview.yml`
	# (trusted workflow_run deploy, has secrets), because GitHub does NOT expose repo
	# secrets to pull_request workflows triggered from forks. See DOC-1228.
	#
	# Triggers:
	# - push to v1 — production deploy (project=docs, --branch=v1). The prod path;
	# CF auto-deploys are disabled, so GHA owns prod end-to-end.
	# - workflow_dispatch — manual run; redeploys the branch's current commit.

	on:
	push:
	branches:
	- v1
	workflow_dispatch:

	# contents: write — the one-merge cut (DOC-1245) materializes + pushes the stable
	# tag named by versions.toml as a pre-build step (mirrors main; inert without one).
	permissions:
	contents: write
	pull-requests: write

	# Opt in early to the Node.js 24 runtime for JavaScript actions. GitHub forces
	# this default on 2026-06-02 and removes Node.js 20 on 2026-09-16. Setting the
	# variable now silences the deprecation warning, tests compatibility with our
	# pinned action versions (checkout@v4, setup-python@v5, upload-artifact@v4,
	# setup-uv@v5, wrangler-action@v3, sticky-pull-request-comment@v2), and gives
	# us a controlled window to bump if any break.
	env:
	FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"

	# Concurrency policy (mirrors main):
	# - production deploys use one `prod` group PER LINE, queued in order (never
	# cancel), so two merges on this line can't race on the CF Pages project,
	# and can't race on cutting the same stable tag (the cut runs in-job, so
	# serializing the job serializes the cut).
	# - workflow_dispatch: own `manual` group, so manual re-runs never block or
	# get blocked by an in-progress production deploy. The ref suffix applies to
	# this arm too, so manual runs are per-line as well -- a manual v1 deploy
	# cannot evict a manual main one, which is the same guarantee `prod` gets and
	# the reason the suffix is unconditional rather than applied to `prod` only.
	# This workflow never runs on `pull_request` (see Triggers above), so there is
	# no PR arm here. PR previews live in build-pr.yml + deploy-pr-preview.yml.
	#
	# `github.ref_name` is what makes the group per-line. Without it this file and
	# main's evaluate to the SAME group string -- both said "one prod group", each
	# reading as though it owned its own queue, and together they formed one shared
	# queue for two lines. "Mirrors main" was the trap, not the safeguard.
	#
	# The failure that produced is silent, and it is documented behaviour rather
	# than a quirk: `cancel-in-progress: false` protects a RUNNING job, but per
	# GitHub's concurrency docs, "any existing pending job or workflow in the same
	# concurrency group will be canceled and the new queued job or workflow will
	# take its place" -- newest wins, cancellation setting notwithstanding.
	# https://docs.github.com/en/actions/using-jobs/using-concurrency
	# So a v1 deploy queued behind a main deploy was discarded the moment a second
	# main deploy arrived, reporting `cancelled` rather than `failure` -- nothing
	# turned red and this line simply did not ship. Observed 2026-08-18.
	concurrency:
	group: ${{ github.workflow }}-${{ github.event_name == 'workflow_dispatch' && 'manual' \|\| 'prod' }}-${{ github.ref_name }}
	cancel-in-progress: false

	jobs:
	build-and-deploy:
	name: "Build and deploy docs"
	runs-on: ubuntu-latest
	timeout-minutes: 30

	steps:
	- name: Checkout repository
	uses: actions/checkout@v4
	with:
	submodules: recursive
	# 0 (was 1): the multi-version assembly + cut checkout tags + v1 into
	# isolated worktrees, so it needs full history + all tags.
	fetch-depth: 0

	- name: Set up Hugo
	uses: peaceiris/actions-hugo@v3
	with:
	hugo-version: '0.161.1'
	extended: true

	- name: Set up Python
	uses: actions/setup-python@v5
	with:
	python-version: '3.12'

	- name: Install uv
	uses: astral-sh/setup-uv@v5

	- name: Print environment
	run: \|
	echo "::group::versions"
	hugo version
	python --version
	uv --version
	echo "::endgroup::"

	# One-merge cut (DOC-1245), mirrored from main: versions.toml names the stable
	# tag /docs/v1 serves. If it doesn't exist yet, THIS merge is the promotion —
	# materialize it (guarded) BEFORE the build, so the v1 line assembles from it in
	# the same job (no cut↔deploy race). Inert until versioning go-live (no
	# versions.toml → skipped), so v1 stays a single static build until then.
	- name: Materialize stable tag if needed (cut)
	if: github.event_name == 'push'
	env:
	GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
	REPO_ROOT: ${{ github.workspace }}
	run: \|
	set -euo pipefail
	if [ ! -f versions.toml ]; then
	echo "no versions.toml → versioning off; skip cut"; exit 0
	fi
	STABLE=$(sed -n 's/^stable = "$.*$"/\1/p' versions.toml \| head -1)
	if [ -z "$STABLE" ]; then echo "versions.toml has no stable → skip"; exit 0; fi
	if git rev-parse -q --verify "refs/tags/$STABLE" >/dev/null; then
	echo "stable tag $STABLE already cut → no-op"; exit 0
	fi
	echo "stable $STABLE not yet cut → materializing at this merge"
	bash unionai-docs-infra/scripts/cut-docs-version.sh --push

	- name: Build dist
	run: \|
	start=$(date +%s)
	# One shared CI build step (DOC-1333): `auto` = the versions.toml gate,
	# identical to the previous inline logic. build-pr.yml calls the SAME
	# script with an explicit mode, so the two build paths cannot drift.
	LATEST_REF=origin/v1 bash unionai-docs-infra/scripts/ci-build-dist.sh auto
	echo "BUILD_SECONDS=$(( $(date +%s) - start ))" >> "$GITHUB_ENV"

	- name: Check generated links
	run: \|
	# The links the GENERATOR writes into dist/. `Check Internal Links`
	# reads content/ and cannot see these: v1 had 1,649 of them pointing at
	# nothing while that job stayed green (DOC-1525).
	# Runs here rather than in its own workflow because it needs the dist
	# this job already built, and a second full Hugo build to check links
	# is not worth the minutes.
	make check-generated-links

	- name: Check rendered images
	run: \|
	# The images the BUILT site serves, resolved the way a browser does --
	# against the page's URL, not the source file's directory. `Check
	# Images` reads content/ and cannot see this: Hugo's render hooks
	# rebase an image src, so a path can be correct in the markdown and
	# wrong in the HTML. Two v1 tutorials shipped images that 404 on the
	# live site while every check passed (DOC-1525, unionai-examples#307).
	make check-rendered-images

	- name: Emit build provenance
	if: success()
	run: \|
	# Write build-info.json at dist/docs/v1/ so it's served at
	# www.union.ai/docs/v1/build-info.json (CloudFront routes
	# /docs/v1/* to v1.docs-dog.pages.dev). On main the equivalent
	# path is dist/docs/build-info.json since CloudFront routes
	# /docs/* (precedence 3) to the main docs-dog.pages.dev origin.
	mkdir -p dist/docs/v1
	cat > dist/docs/v1/build-info.json <<EOF
	{
	"builder": "github-actions",
	"repository": "${{ github.repository }}",
	"workflow_file": ".github/workflows/build-and-deploy.yml",
	"run_id": "${{ github.run_id }}",
	"run_url": "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}",
	"commit": "${{ github.sha }}",
	"ref": "${{ github.ref_name }}",
	"event": "${{ github.event_name }}",
	"built_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
	}
	EOF
	cat dist/docs/v1/build-info.json

	- name: Build summary
	if: always()
	run: \|
	echo "::group::dist tree (top 2 levels)"
	find dist -maxdepth 2 -mindepth 1 -print 2>/dev/null \| sort \|\| true
	echo "::endgroup::"
	echo "::group::dist size"
	du -sh dist 2>/dev/null \|\| true
	du -sh dist/docs/v2 dist/docs/v1 2>/dev/null \|\| true
	echo "::endgroup::"
	if [ -n "${BUILD_SECONDS:-}" ]; then
	echo "Build wall time: ${BUILD_SECONDS}s"
	fi

	- name: Upload dist artifact
	if: success()
	uses: actions/upload-artifact@v4
	with:
	name: dist
	path: dist/
	retention-days: 7
	if-no-files-found: error

	- name: Sanitize branch name for CF Pages
	if: success()
	id: branch
	run: \|
	# CF Pages branch names: lowercase alphanumeric + hyphens, max 28 chars.
	# Production-only workflow, so `github.ref_name` is always `v1`
	# (push) or the dispatched ref. The `pr-<num>-` aliasing lives in
	# deploy-pr-preview.yml, which is what handles PR events.
	raw="${{ github.ref_name }}"
	sanitized=$(echo "$raw" \| tr '[:upper:]' '[:lower:]' \| sed -E 's#[^a-z0-9]+#-#g' \| sed -E 's#^-+\|-+$##g' \| cut -c1-28)
	echo "Source branch: $raw → CF Pages branch: $sanitized"
	echo "name=$sanitized" >> "$GITHUB_OUTPUT"

	- name: Deploy to Cloudflare Pages
	if: success()
	id: deploy
	# Step-level cap: a normal CF Pages deploy is ~1-3 min. Without this a
	# hung wrangler upload eats the whole job's timeout-minutes budget
	# (incl. the build) before failing — observed once at ~26 min on a large
	# API-docs regen. Fail fast so the deploy can be re-run. See DOC-1229.
	timeout-minutes: 10
	uses: cloudflare/wrangler-action@v3
	with:
	apiToken: ${{ secrets.CLOUDFLARE_PAGES_API_TOKEN }}
	accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
	# --commit-dirty: make dist regenerates tracked files (notebooks,
	# API docs), so the working tree is always dirty by the time we hit
	# wrangler. The warning is noise, not a real condition.
	# We don't pass --commit-hash because we use fetch-depth: 1 above
	# (shallow checkout), which means the local repo can't resolve the
	# SHA wrangler tries to look up and would emit "fatal: bad object".
	# wrangler-action records the commit metadata on its own via the
	# GITHUB_SHA env var.
	command: pages deploy ./dist --project-name=docs --branch=${{ steps.branch.outputs.name }} --commit-dirty=true

	- name: Update search index
	# After the deploy, not before: the index should describe what is now
	# served. Scoped to the slices THIS branch built -- v1 only -- so main
	# (v2 + latest) and this branch cannot clobber each other's records.
	#
	# Skips itself when the secret is absent, so forks and any repo without
	# Algolia credentials still deploy normally.
	if: success() && github.event_name == 'push'
	timeout-minutes: 15
	env:
	ALGOLIA_DOCS_2_APPLICATION_ID: ${{ secrets.ALGOLIA_DOCS_2_APPLICATION_ID }}
	ALGOLIA_DOCS_2_WRITE_API_KEY: ${{ secrets.ALGOLIA_DOCS_2_WRITE_API_KEY }}
	run: make index-search

	- name: Deploy summary
	if: success()
	run: \|
	echo "## Deployment" >> "$GITHUB_STEP_SUMMARY"
	echo "" >> "$GITHUB_STEP_SUMMARY"
	echo "- Project: \`docs\`" >> "$GITHUB_STEP_SUMMARY"
	echo "- Branch (CF Pages): \`${{ steps.branch.outputs.name }}\`" >> "$GITHUB_STEP_SUMMARY"
	echo "- Commit: \`${{ github.sha }}\`" >> "$GITHUB_STEP_SUMMARY"
	if [ -n "${{ steps.deploy.outputs.deployment-url }}" ]; then
	echo "- Deployment URL: ${{ steps.deploy.outputs.deployment-url }}" >> "$GITHUB_STEP_SUMMARY"
	fi

Navigation Menu

Uh oh!

docsy(v1): bump infra for the setup-doc refresh (#1566) #854

Workflow file

docsy(v1): bump infra for the setup-doc refresh (#1566) #854

Uh oh!

Workflow file for this run