chore(ci): publish docs for releases and branch updates 🚀

[kp2pml30]

Problem And Outcome

Docs currently publish nightly or manually, so successful releases and branch updates do not publish their matching documentation

1. Dispatch docs after the release publishing job succeeds, selecting the exact release tag as both source ref and site version
2. Publish pushed commits on v0.6 under v0.6.x, and on v0.6-dev under v0.6-dev
3. Cancel previous docs runs for the same target version while allowing different versions to build concurrently
4. Retry rejected site pushes up to 5 attempts, rebuilding the commit against the latest site main so concurrent directories and versions.json entries survive

Nightly main publishing and manual version/preferred inputs remain available; unchanged output does not create a commit

Implementation And Validation

deploy-docs --push requires a clean, disposable checkout and reapplies the already-built docs on each retry rather than rebasing generated JSON conflicts

• pytest -q support/ci/unit_tests: 92 passed, including 6 publication tests with real Git repositories covering a concurrent push, preferred-version preservation, retry exhaustion, dirty checkout rejection, replacement/deletion, unchanged output, and staging without pushing
• Pre-commit hooks and docs-index check passed
• Actionlint workflow validation passed; ShellCheck reports only the existing SC2035 warning in the unchanged release checksum command, reproduced against the base branch
• Independent review found no actionable issues
• Live GitHub dispatch, full Sphinx/Nix builds, and site deployment were not run locally; no E2E requested

Delivery Context

Targets v0.6-dev; no cross-repository code dependencies or executor changes
Requires the existing DOCS_DEPLOY_KEY for the site repository and job-scoped actions: write for release dispatch
The workflow must reach v0.6 before that branch publishes automatically; dispatch and scheduling also require it on the default branch
Rollback: revert this change to restore nightly/manual publication without push retries

Summary by CodeRabbit

• New Features
  • Documentation deployments now run for releases, pushes to the v0.6 and v0.6-dev branches, nightly schedules, and manual requests.
  • Release builds now trigger a documentation deployment for the released version.
  • Deployments retry failed pushes up to five times and retain concurrent updates to other documentation versions.
• Documentation
  • Updated publishing guidance with deployment triggers, version targets, permissions, retry behavior, and manual deployment requirements.

[github-actions]

GenVM PR actions

Tick a box to run it (the box unticks itself when handled). Actions only run while the PR has the ci-safe label.

• Force run full tests
• Provision executor PRs

Commands

• /genvm-run-tests — run full tests once for the current manager snapshot
• /merge — queue the exact manager snapshot through the App-owned E2E merge train

[coderabbitai]

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

⚙️ Run configuration

• Configuration used: Repository: genlayerlabs/genvm-manager/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 3b1ac3d3-1d8b-49e7-9c72-7d3991924e74

📥 Commits

Reviewing files that changed from the base of the PR and between 1a097ef and df7ad64.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: genlayerlabs/genvm-manager/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: fd6a6331-6077-48dd-ac84-1f9dc6b57099

📥 Commits

Reviewing files that changed from the base of the PR and between ec5c8ac and 1a097ef.

📒 Files selected for processing (5)

• .github/workflows/docs_nightly.yaml
• .github/workflows/release.yaml
• docs/contributing/howto/building/docs.md
• support/ci/tools/deploy_docs.py
• support/ci/unit_tests/test_deploy_docs.py

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

The docs workflow now deploys nightly, on configured branch pushes, and from release-tag dispatches. deploy_docs.py --push resets a clean checkout to origin/main, stages the selected documentation version, and retries failed pushes up to five attempts.

Changes: Documentation deployment

Layer / File(s)	Summary
Publishing behavior and validation support/ci/tools/deploy_docs.py, support/ci/unit_tests/test_deploy_docs.py	DeployDocs supports staging without publishing and publishing with --push. Publishing rejects a dirty checkout, fetches and resets to origin/main, and retries failed pushes up to five attempts. Tests cover updated documentation, unchanged output, concurrent updates, rejected pushes, dirty checkouts, and staging without publishing.
Workflow triggers and release dispatch .github/workflows/docs_nightly.yaml, .github/workflows/release.yaml, docs/contributing/howto/building/docs.md	The docs workflow handles nightly, manual, configured branch-push, and release-tag dispatch events. It resolves a version, checks out the selected ref, and runs deploy-docs --push. The release workflow dispatches the docs workflow at the release tag. The documentation describes trigger refs, target directories, permissions, retries, and checkout requirements.

Priority: ⬇️ Low

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

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant ReleaseJob
  participant docs_nightly.yaml
  participant deploy_docs.py
  participant SiteOriginMain
  ReleaseJob->>docs_nightly.yaml: Dispatch workflow at release tag with version input
  docs_nightly.yaml->>deploy_docs.py: Run with --push
  deploy_docs.py->>SiteOriginMain: Push documentation commit

Loading

Merge Risk: ⚪ Minimal · up to 1a097

The documentation publishing changes are ready to merge after normal checks. Live dispatch and deployment remain untested locally, but no concrete failure was identified.

Pre-merge checks: 4 · 1

Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 2 files. (3 skipped: 3…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks (4 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly summarizes the main changes: publishing documentation for releases and branch updates. The chore(ci) prefix is appropriate, and the title is concise and specific.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 2 files. (3 skipped: 3 unsupported.)

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

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

[kp2pml30]

/genvm-run-tests

[kp2pml30]

/run-e2e all

[ci-core-e2e-runner]

E2E status was updated. Follow the current E2E and merge checks on this PR. Detailed diagnostics are available internally.

[github-actions]

👀 Full tests are running for df7ad64777d8: open run #38585329197