ci: notify the central documentation workflow after Docs succeeds

[lyfne123]

Summary

After a successful upstream main Docs run, an opt-in completion listener requests the website's central documentation build using a website-scoped GitHub App token. Notification failures are reported separately from the completed Docs validation. Existing Pages publishing remains the default until an explicit handoff switch is set.

Changes

• Filter notifications to the configured upstream main Docs workflow and send its repository, source SHA, run ID, and attempt to the website's docs-site.yml on main.
• Require DOCS_SITE_NOTIFY_ENABLED, DOCS_SITE_APP_ID, and DOCS_SITE_APP_PRIVATE_KEY before notifying; the App token only requests website Actions write permission.
• Allow DOCS_SITE_PUBLISHER=central to retire the original artifact upload and deployment after the central artifact and Pages routing handoff are verified.

Verification

• pre-commit run --files .github/workflows/docs.yml .github/workflows/notify-docs-site.yml: all applicable checks passed.
• actionlint -color .github/workflows/docs.yml .github/workflows/notify-docs-site.yml: passed.
• git diff --check: passed.
• The companion website receiver was exercised against real successful Docs run metadata, with 35 publication tests and a strict bilingual build passing. The live App dispatch remains untested until both workflows are merged into their default branches and the App is configured; notification and publication switches remain disabled.
• Hosted GitHub Actions: the PR Docs build passed and Pages deployment was skipped as intended. Other repository lint jobs are still running.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-10T02:20:07.030603Z	b76e1bd	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 0aecb4e0-397c-4044-83d8-ca3ce7a69c53

📥 Commits

Reviewing files that changed from the base of the PR and between afd6f60 and b76e1bd.

📒 Files selected for processing (2)

• .github/workflows/docs.yml
• .github/workflows/notify-docs-site.yml

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

The change gates local Docs artifact publishing and deployment with DOCS_SITE_PUBLISHER. A new workflow detects successful Docs runs, creates a scoped GitHub App token, and dispatches the central documentation-site workflow with source metadata.

Changes

Docs publishing handoff

Layer / File(s)	Summary
Local publication gate .github/workflows/docs.yml	The workflow skips artifact upload and deployment when DOCS_SITE_PUBLISHER is central. Comments document the pilot handoff conditions.
Central site notification .github/workflows/notify-docs-site.yml	The workflow validates the triggering run and required secrets, creates a repository-scoped token, and dispatches docs-site.yml with source run metadata.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to b76e1

Documentation publishing remains unchanged by default; when enabled, successful main Docs runs can notify the central site workflow without leaving local Pages deployment enabled in central mode. The change is ready to merge.

Sequence Diagram(s)

sequenceDiagram
  participant DocsWorkflow
  participant NotifyWorkflow
  participant GitHubApp
  participant CentralDocsRepository
  DocsWorkflow->>NotifyWorkflow: completed successful main run
  NotifyWorkflow->>GitHubApp: create repository-scoped token
  GitHubApp-->>NotifyWorkflow: actions write token
  NotifyWorkflow->>CentralDocsRepository: dispatch docs-site.yml with source metadata

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The description clearly explains the new opt-in notification workflow, its configuration, security scope, fallback behavior, and verification results. It is directly related to the changeset.
Title check	✅ Passed	The title clearly and concisely identifies the main change: notifying the central documentation workflow after the Docs workflow succeeds.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit reads each line,
The patch grows clear beneath the moon,
Small changes hop in place,
Tests guard the garden path,
Reviews bloom before the dawn.}

_{Comment @coderabbitai help to get the list of available commands.}