QVAC-23049 infra: pin docs promotion to an explicit, pre-validated commit

[BrunoCampana]

What problem does this PR solve?

Promoting docs to production was all-or-nothing: the workflow resolved origin/main inside the job and advanced docs-production to whatever the tip of main happened to be.

• There was no way to choose how far to advance the pointer. main accumulates commits continuously, from everyone. The state that has been verified and is ready to publish is rarely its current tip — the operator needs to promote up to a chosen commit and leave the work that landed after it on staging. The workflow could not express that.
• Because the target was resolved when the job ran — after the docs-production approval, which can hold for hours — the promoted set could keep growing between dispatch and push, sweeping in commits nobody had verified.
• An environment gate pauses a job before its first step runs, so every validation happened only after a reviewer had been paged. A request that could never succeed (branches diverged, nothing to promote) was discovered by interrupting someone first.
• The approver had no view of what the promotion would actually contain — no target SHA, no commit list — at the moment of deciding.

How does it solve it?

• The commit to promote is now a required workflow_dispatch input. The operator decides how far docs-production advances, instead of always taking the tip of main, and the promotion stays pinned to that commit however long the approval takes.
• Validation moved into a separate ungated preflight job. It rejects an unknown commit, a commit not contained in main, a commit behind docs-production, and divergence that makes the fast-forward impossible — all while the run is still unattended. The gated job is reached only by a promotion already known to be valid.
• Requiring containment in main is a security boundary, not a convenience. Without it the dispatch input would be a path to deploy unreviewed code straight to the production site.
• Preflight publishes the resolved SHA and the exact list of commits being promoted to the run summary, and run-name carries the target commit, so the approver can see what they are approving before clicking.
• A no-op never pages anyone. If docs-production already points at the requested commit, preflight skips the gated job entirely and the run ends green.
• The gated job re-asserts its invariants after the wait. It re-checks containment in main and refuses a target already contained in docs-production — git merge --ff-only <ancestor> reports "Already up to date" and exits 0, so without that check a branch that advanced past the target would produce a green run that pushed nothing while logging a successful promotion.
• Least privilege: top-level permissions dropped to contents: read, with contents: write only on the job that pushes; preflight checks out with persist-credentials: false so it cannot push at all. Both jobs declare timeout-minutes.

docs/website/docs-workflow.md is updated to describe the input, the two jobs, and the full set of failure conditions.

[github-actions]

Review Status

Current Status: ❌ PENDING
Approvals so far: none

Pending reviews: Needs 1 Management or Team Lead, and 1 more from Management, Team Lead, or Member.

[github-actions]

License compliance — clean

No new dependency license findings in this PR.

Warn-only (shadow) mode — this check does not block merges yet.

Updated automatically by the canonical license compliance workflow.

NOTICE presence (advisory)

Missing NOTICE (advisory, does not block):

• ./.github/actions/release-merge-guard
• ./packages/vla-ggml/sim/server
• ./packages/asr-ggml/benchmarks/server
• ./packages/embed-llamacpp/benchmarks/performance
• ./packages/embed-llamacpp/benchmarks/server
• ./packages/llm-llamacpp/benchmarks/performance
• ./packages/llm-llamacpp/benchmarks/server
• ./packages/ggml-coload-smoke
• ./packages/sdk/e2e
• ./packages/fabric/test/integration
• ./docs/website

[github-actions]

Workflow security (shadow mode)

zizmor found 1185 finding(s) in .github/ (highest severity: high). This check is warn-only and does not block the merge.

Findings are annotated inline on the changed files and listed in the job summary.

Reproduce locally:

pipx run zizmor==1.27.0 --offline .github/