docs: add versioned documentation with mike - #233
Conversation
Align the public docs site with release artifacts by publishing versioned docs to gh-pages: latest release as default, main as a preview. Adds GitHub Actions deploy workflow, Netlify gh-pages publishing config, and release checklist updates for future releases. Fixes kubernetes-sigs#222
k8s-ci-robot
added
the
do-not-merge/work-in-progress
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: ibm-adarsh The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
Warning Review limit reached
Next review available in: 2 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (13)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
k8s-ci-robot
added
the
needs-ok-to-test
|
Hi @ibm-adarsh. Thanks for your PR. I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with Tip We noticed you've done this a few times! Consider joining the org to skip this step and gain Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
k8s-ci-robot
added
cncf-cla: yes
ibm-adarsh
changed the title
Exclude site-src/README.md from the built site to avoid index.md conflict under --strict, fix API reference links, and allow deploy-preview builds while production remains on gh-pages.
❌ Deploy Preview for mcp-lifecycle-operator failed. Why did it fail? →
|
|
The skipped jobs are expected behavior. This workflow has four jobs, each gated by a specific event:
Since this run was triggered by a PR ( This is intentional: deploy jobs publish documentation to |
✅ Deploy Preview for mcp-lifecycle-operator ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
ArangoGutierrez
left a comment
ArangoGutierrez
left a comment
There was a problem hiding this comment.
WIP is in good shape — actions are SHA-pinned and the deploy jobs use least-privilege contents:write. Two gh-pages publishing concerns worth hardening before this graduates from draft.
- The three deploy jobs (deploy-main on push, deploy-release on release, deploy-manual) all run
mike deploy --pushagainst gh-pages, but there's no concurrency control. A merge to main landing during a release publish has both jobs commit and push gh-pages at once, giving a non-fast-forward push failure or a clobbered version. Add a workflow-level concurrency group (e.g. group: docs-deploy-gh-pages, cancel-in-progress: false). (.github/workflows/docs.yaml:32) - This switches the live working tree to gh-pages mid-script.
make api-ref-docson line 56 may leave tracked docs modified, so under set -e the checkout can abort the run after mike has already pushed. Alsogit fetch origin gh-pagesonly advances the remote-tracking ref, so the latergit push origin gh-pagesisn't reconciled with a concurrent update and can fail non-fast-forward. Consider syncing netlify.toml from a dedicated clean clone/worktree, orgit checkout -B gh-pages origin/gh-pagesafter stashing generated files. (hack/mkdocs/deploy.sh:82)
| type: boolean | ||
| default: true | ||
|
|
||
| permissions: |
There was a problem hiding this comment.
The three deploy jobs (deploy-main on push, deploy-release on release, deploy-manual) all run mike deploy --push against gh-pages, but there's no concurrency control. A merge to main landing during a release publish has both jobs commit and push gh-pages at once, giving a non-fast-forward push failure or a clobbered version. Add a workflow-level concurrency group (e.g. group: docs-deploy-gh-pages, cancel-in-progress: false).
There was a problem hiding this comment.
Thanks for catching this — great point about overlapping release and main deploys racing on gh-pages.
Addressed in fe0d351: added a workflow-level concurrency group that serializes deploy runs (docs-deploy-gh-pages) while keeping PR lint runs on their own per-PR group so doc validation isn't blocked by deploys.
Happy to adjust if you'd prefer a separate deploy-only workflow instead.
|
|
||
| echo "Ensuring Netlify configuration on gh-pages..." | ||
| git fetch origin gh-pages | ||
| git checkout gh-pages |
There was a problem hiding this comment.
This switches the live working tree to gh-pages mid-script. make api-ref-docs on line 56 may leave tracked docs modified, so under set -e the checkout can abort the run after mike has already pushed. Also git fetch origin gh-pages only advances the remote-tracking ref, so the later git push origin gh-pages isn't reconciled with a concurrent update and can fail non-fast-forward. Consider syncing netlify.toml from a dedicated clean clone/worktree, or git checkout -B gh-pages origin/gh-pages after stashing generated files.
There was a problem hiding this comment.
Thanks for the detailed review on this — really helpful.
Updated in fe0d351: the Netlify config sync now uses a dedicated git worktree checked out from origin/gh-pages instead of switching the live working tree. That avoids disturbing the source checkout after mike deploy, and combined with the concurrency group, reduces the non-fast-forward push risk you flagged.
Appreciate the correction on the gitignored reference/index.md — that clarified which part of the concern still applied.
ArangoGutierrez
left a comment
ArangoGutierrez
left a comment
There was a problem hiding this comment.
This is the right shape for #222: mike-versioned docs with latest as the default (tracking release tags) and main as a preview matches the stated preference, and the release checklist updates close the process gap. The strict docs build passes locally and the workflow is well-scoped (SHA-pinned actions, least-privilege permissions, fetch-depth 0). Two things to harden before this graduates from draft: add a workflow-level concurrency group so the gh-pages deploy jobs serialize (they currently race), and document the merge -> bootstrap -> switch-Netlify ordering, since the intentional exit 1 in netlify.toml means merge alone doesn't complete the migration. One correction to my earlier review: the deploy.sh dirty-tree concern doesn't apply (the generated reference doc is gitignored), but the non-fast-forward push in that same block is real and folds into the concurrency fix. With concurrency added and the manual switch sequenced, this is good to move forward.
| type: boolean | ||
| default: true | ||
|
|
||
| permissions: |
There was a problem hiding this comment.
Consider a workflow-level concurrency group so the deploy jobs can't push gh-pages at the same time:
concurrency:
group: docs-deploy-gh-pages
cancel-in-progress: falseA release publish overlapping a main push (each doing mike deploy --push, plus the set-default and netlify.toml pushes) can otherwise fail non-fast-forward or clobber a version.
There was a problem hiding this comment.
Agreed — implemented in fe0d351 with the same docs-deploy-gh-pages concurrency group (cancel-in-progress: false). Thanks for following up on this.
| - "crd-ref-docs.yaml" | ||
| - "api/v1alpha1/**" | ||
| - ".github/workflows/docs.yaml" | ||
| push: |
There was a problem hiding this comment.
The push trigger has no paths: filter, so every merge to main redeploys the main preview and commits to gh-pages even for unrelated changes. Mirroring the pull_request paths here would cut noise and shrink the concurrency window.
There was a problem hiding this comment.
Good call — added the same paths filter to the push trigger (via YAML anchor shared with pull_request) in fe0d351, so unrelated merges to main no longer redeploy the preview or commit to gh-pages. Thanks for the suggestion.
| # intentionally. PR deploy previews still build from the PR branch. | ||
| [build] | ||
| publish = "site" | ||
| command = "echo 'Docs are published from gh-pages by GitHub Actions. Point Netlify production branch to gh-pages. See site-src/README.md.' && exit 1" |
There was a problem hiding this comment.
Nice forcing function. Worth spelling out the required order in the PR body so an approver doesn't half-migrate: merge -> run the manual Docs workflow to bootstrap latest on gh-pages -> switch the Netlify production branch to gh-pages. Until the switch, main production builds fail here by design (last good deploy stays live).
There was a problem hiding this comment.
Great idea — documented the required order in the PR body, netlify.toml, and site-src/README.md (fe0d351):
- Merge → 2. Manual Docs workflow to bootstrap
latest→ 3. Switch Netlify production branch togh-pages
Thanks for making sure approvers have a clear sequence and don't half-migrate.
|
|
||
| echo "Ensuring Netlify configuration on gh-pages..." | ||
| git fetch origin gh-pages | ||
| git checkout gh-pages |
There was a problem hiding this comment.
One correction to the earlier review: site-src/reference/index.md is gitignored, so make api-ref-docs leaves no tracked changes and this git checkout gh-pages won't abort on that. The remaining risk is the git push origin gh-pages below racing a concurrent deploy (the git fetch only moves the remote-tracking ref). Writing netlify.toml from a dedicated clone/worktree instead of switching the live tree, plus the concurrency group, would make this robust.
There was a problem hiding this comment.
Thanks for the correction on the gitignored generated file — that helped narrow the fix.
In fe0d351, the remaining push race is addressed with the concurrency group plus writing netlify.toml from a dedicated git worktree on origin/gh-pages rather than checking out gh-pages in the live tree. Open to exploring a fully separate clone if you'd prefer that approach.
|
/ok-to-test |
kubernetes-prow
Bot
added
ok-to-test
Serialize gh-pages deploys with a concurrency group, limit main preview deploys to docs-related paths, sync netlify.toml via a git worktree, and document the merge -> bootstrap -> Netlify switch migration sequence.
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: ibm-adarsh The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
Thanks @ArangoGutierrez for the thorough review — really appreciate you taking the time to walk through the gh-pages deploy edge cases and the migration sequencing. All feedback has been addressed in
I've replied inline on each thread with details. Happy to explore further refinements — e.g. a separate deploy-only workflow — if you think that would be cleaner. Planning to drop the |
ibm-adarsh
changed the title
|
/hold cancel removing WIP and ready for review. |
kubernetes-prow
Bot
removed
the
do-not-merge/work-in-progress
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #233 +/- ##
=======================================
Coverage ? 73.92%
=======================================
Files ? 15
Lines ? 1822
Branches ? 0
=======================================
Hits ? 1347
Misses ? 432
Partials ? 43 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
|
@ibm-adarsh sorry for the late response - but should this be updated ? |
Sure @matzew , Will start looking into it again. Thanks for the reminder. |
4 participants
Summary
releases/latest) and main (development preview).github/workflows/docs.yamlto lint docs on PRs, deploymainpreview on push, and deploy release docs on GitHub release publishgh-pagesbranch (with one-time Netlify config change documented insite-src/README.md)Closes #222
Post-merge migration sequence
Complete these steps in order — merge alone does not finish the migration:
mainlatest: run Actions → Docs → Deploy docs (manual) withv0.1.0(or the current release tag)gh-pages(build command empty, publish/)Until step 3, main-branch production Netlify builds fail by design (
netlify.tomlintentionalexit 1); the last good production deploy stays live.Test plan
v0.1.0to bootstrap thelatestversion ongh-pagesgh-pages(build command empty, publish/)latestandmainlatestupdates automatically