Ci/docs native pages deploy - #3001
Merged
kubernetes-prow[bot] merged 4 commits intoAug 11, 2026
Merged
Conversation
…ranch
The docs deploy has been failing since 2021. The gh-pages branch has a
protection rule requiring the EasyCLA status check and disallowing force
pushes, but JamesIves/github-pages-deploy-action force-pushes a synthetic
branch to it, so every push has been declined:
remote: error: GH006: Protected branch update failed for refs/heads/gh-pages.
remote: - Required status check "EasyCLA" is expected.
The branch has exactly two commits, both from 2021-07-16, and the live site
still serves that build. Separately, the repo's Pages publishing source is
already build_type=workflow, so the branch is no longer the publishing source
and no workflow was able to publish at all.
Switch to actions/upload-pages-artifact + actions/deploy-pages, which
publishes through the Pages API and never touches a protected branch.
Also consolidate the two docs workflows. deploy-docs.yml (typedoc) and
deploy-docs-v2.yml (Docusaurus) both deployed to the same Pages root with
--delete and would clobber each other. The standalone typedoc build is
redundant: docs/ already wires up docusaurus-plugin-typedoc, which generates
the SDK reference into docs/sdk during the site build. Root typedoc.json also
has out="docs", which writes typedoc HTML into the Docusaurus source dir.
- fold deploy-docs-v2.yml into deploy-docs.yml, split into build + deploy jobs
- drop the standalone typedoc build; the site build covers it
- narrow contents: write to contents: read; scope pages/id-token to deploy
- add concurrency group with cancel-in-progress: false
- keep the PR trigger so link validation still runs on PRs
- drop the paths filter, which was scoped to typedoc inputs and would skip
deploys for docs-only content changes
Verified locally: docs build emits 95 SDK reference pages plus api-reference,
models and examples, and the link check reports 0 bad links and 0 bad anchors
across 30225 links.
Folding the PR build into the deploy workflow meant gating half the steps on `if: github.event_name == 'push'`, which is noisy and made the deploy path harder to read. Split them into two single-purpose workflows: - docs-build.yml runs on pull_request: build plus link/anchor validation, contents: read only, no Pages permissions, and cancel-in-progress so stale PR runs are dropped. - deploy-docs.yml runs on push to main: build, upload artifact, deploy. No event conditionals left. Also drop the duplicated version-check.js step. test.yml already runs it, and its paths filter covers package.json, package-lock.json and version-check.js itself, so the inputs that check validates always trigger it. Broken internal links still block a deploy independently of the PR job, since docusaurus.config.ts sets onBrokenLinks and onBrokenAnchors to 'throw'. Verified locally from a clean tree: build succeeds and the link check reports 0 bad links and 0 bad anchors across 30225 links in 378 files.
Add workflow_dispatch to the deploy workflow so docs can be re-published on demand, e.g. after a failed deploy or a Pages settings change, without having to push an empty commit to main.
workflow_dispatch can be triggered from any ref, and the ref chosen is what gets built and published, so a manual run from a feature branch would publish that branch to the live docs site. Guard the build job with `github.ref == 'refs/heads/main'`. The push trigger is already main-only, so this only constrains manual runs. deploy needs build, and GitHub skips dependent jobs when a needed job is skipped, so the whole workflow no-ops on any other ref. This is defence in depth alongside restricting the github-pages environment's deployment branches to main.
kubernetes-prow
Bot
added
cncf-cla: yes
kubernetes-prow
Bot
added
the
approved
kubernetes-prow
Bot
added
the
lgtm
Contributor
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: cjihrig, davidgamero The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
convert deploy-docs workflow to use github actions/deploy-pages action to fully deprecate gh-pages branch
add docs built test workflow to run on PRs