[Alexandre Zollinger Chohfi (azchohfi)]

Summary

A release tag publishes the versioned docs site, so the github-pages environment's deployment-branch policy has to admit both main (branch) and v* (tag). That policy lives in repository settings rather than in this repo, so nothing in docs.yml reveals it — and the failure it causes is easy to misread. This adds a Which refs may deploy subsection to docs/contributing/release-runbook.md documenting the requirement, the failure signature, and the recovery step.

The prompt for writing it down: when v0.1.0-preview.15 was pushed, the environment had exactly one policy, {"name": "main", "type": "branch"} — correct back when main was the only publisher — so the tag was rejected with Tag "v0.1.0-preview.15" is not allowed to deploy to github-pages due to environment protection rules. The run then reports publish: success and deploy: failure, which reads like a partial success but isn't: gh-pages really does contain the new version and the latest alias really has moved, yet nothing is ever served, so the live site silently keeps showing the previous release. A v* tag policy was added and re-running the failed run (34577954754) turned it green; the environment now lists branch: main and tag: v*.

The new subsection covers:

• Why the policy must list both a branch and a tag entry, and that it is invisible from the workflow YAML.
• The split-failure signature (publish green, deploy red, site stale, branch already correct), including the verbatim error, so it is recognisable on sight.
• The verification command, which should print branch: main and tag: v*.
• The command to add a missing entry, noting it requires repository admin — maintain gets HTTP 403: Must have admin rights to Repository.
• The recovery step: dispatch Publish docs on main, since the Pages artifact is the whole gh-pages branch, so a deploy from any allowed ref serves every version already committed to it.

Step 3 of Monitor and publish also picks up a one-clause cross-reference telling the release owner to check both jobs, since that checklist is where someone stands when this bites.

Linked issue / spec

N/A — no tracking issue. This documents an operational prerequisite of the versioned docs site introduced by #1199 (docs/specs/057-release-channels.md covers the release-channel side).

No CHANGELOG entry: the changelog does accept infrastructure entries (precedent: the issue #680 "test infrastructure only" entry), and #1199 already added a Changed entry for the versioned docs site itself. This PR only documents an operational prerequisite of that already-recorded change, so a second entry would be noise.

Test plan

Markdown-only, under docs/contributing/ (authored, not generated — the generated surface is docs/guide/**, compiled from docs/_pipeline/templates/*.md.dt, and nothing there is touched). No build or test impact. Verified instead:

• Ran the documented verification command verbatim, including its PowerShell backtick continuation, and confirmed it prints branch: main and tag: v* — so the command in the doc is the command that works, not a paraphrase.
• Checked every in-file anchor link resolves to a real heading, with a positive control — the same probe flags an injected bogus anchor, so the zero-broken result is a measurement rather than a broken grep. Confirms both the new #which-refs-may-deploy and the pre-existing #versioned-documentation-site that CHANGELOG.md:123 links.
• Confirmed this file is not in the mkdocs.yml nav, so no mkdocs build --strict gate covers it and the anchor check above is the only instrument.
• Checked no doc-pipeline test or CI job asserts this file's content or structure.
• Ran the repo's pr-review skill (scoped to security / correctness / docs-and-samples / multi-model; the API-ergonomics, alternative-solution, test-coverage and packaging dimensions have no surface in a prose diff). One medium finding, fixed before pushing — see below.

Risk / breaking changes

None. No public API, no behavior, no build surface — prose only.

One review finding is worth recording because it was a real inaccuracy rather than a style note. The first draft said the stranded release "is rendered and latest has moved to it" unconditionally, but .github/workflows/docs.yml:105-113 only moves latest inside if [ "$GITHUB_REF_NAME" = "$newest" ] — an older or backported tag is published without --update-aliases. That directly contradicted the paragraph immediately above the new subsection ("A tag only takes the latest alias if it is the highest tag by version sort"). Reworded to "the latest alias has already moved to it if the tag qualifies under the version-sort rule above", and a cross-check against the workflow confirmed the corrected wording. Since the entire deliverable here is factual accuracy, an overstatement a release owner might rely on mid-incident was worth catching.