[8.19] Fix the reference documentation publish on release - #8985
Merged
Merged
Conversation
The DocFx job of the CD workflow has failed on every 8.19 release since 8.19.24, because pushing the generated site to the refdoc branch gets a read-only token: remote: Permission to elastic/elasticsearch-net.git denied to github-actions[bot] The repository default for GITHUB_TOKEN is read-only. On main that is compensated for by an explicit grant on docfx.yml and on both of its callers, since a called workflow cannot request more than its caller holds. Those grants were never backported (#8918, #8948). Taking main's docfx.yml wholesale brings the refdoc branch fixes along as well (#8850, #8851, #8852, #8853), so an 8.19 release no longer pushes the payload that broke the Pages deployments, and it regenerates the root version index and the retention redirects the same way a 9.x release does. The serverless removal (#8764) is deliberately not taken, because 8.19 still releases a serverless flavor and its release job and tag guards have to stay as they are.
A manual run can only publish under the name of the dispatched ref, which makes it unusable for republishing a specific version. Backfilling a release whose DocFx job failed cannot go through the tag either, because workflow_dispatch reads the workflow file from the dispatched ref and the existing tags still carry the version without the permission grant. Dispatching from the release branch instead resolves github.ref_name to the branch name, which would publish the site into a folder named after the branch. An omitted input arrives as an empty string rather than being absent, so it would override the default declared in docfx.yml. The fallback has to be applied by the caller; an empty name would otherwise make the commit step target the refdoc root.
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
1 participant
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.
Summary
Restores the
DocFxjob of theCDworkflow on8.19and brings the reference documentation workflows in line withmain.docfx.ymlis taken frommainunchanged, so an8.19release now trims the generated site before pushing,regenerates the root version index and applies the version retention redirects exactly as a 9.x release does. Both
callers of
docfx.ymlreceive thecontents: writegrant they were missing, anddocfx_manual.ymlgains an optionalnameinput so a specific version can be republished.Intention
The
DocFxjob has failed on every8.19release since 8.19.24, sorefdoccurrently ends at 8.19.23 and neither8.19.24 nor 8.19.25 was ever published. The push to
refdocis rejected:The repository default for
GITHUB_TOKENis read-only. Onmainthat is compensated for by an explicit grant ondocfx.ymland on both of its callers, since a called workflow cannot request more than its caller holds. Those grantswere added in #8918 and #8948 and were never backported.
A permissions-only fix would leave
8.19pushing the payload that caused the oversizedrefdocfailures, and it wouldnot regenerate the root version index, so
docfx.ymlis synced in full instead.Changes
docfx.yml: replaced withmain's version, folding in Fix GitHub Pages deployments failing due to oversized refdoc branch #8850, Enforce documentation version retention policy via automated redirects #8851, Add basic styling to reference docs html and generate a static index #8852, Point to the next supported minor instead of the bleeding edge version #8853 and fix: add explicit permissions to GitHub Actions workflows #8918. The file is now byteidentical on both branches.
release_stack.yml: addedcontents: writeto thedocfxjob. The serverless tag guards and theflavorandsolutioninputs of thereleasejob are untouched, so Removeserverlessfrom release workflows #8764 is deliberately not taken.docfx_manual.yml: addedcontents: writeand an optionalnameinput selecting the folder to publish into.Related
Backports #8850, #8851, #8852, #8853, #8918 and #8948.
The
nameinput ofdocfx_manual.ymlis added tomainin #8984, so the file stays identical on both branches.Notes
Verified by replaying the redirect script from the backported
docfx.ymlagainst the currentrefdoclayout with thepublished version set to
8.19.25. It exits cleanly, keeps 9.5.1 as the bleeding edge entry, retains 9.5.1, 9.4.2,9.3.6 and 8.19.25, and redirects the superseded 8.19.x folders as well as 8.16 through 8.18 to 8.19.25.
actionlintreports no findings on the three changed files.
Backfilling 8.19.24 and 8.19.25 still needs a manual run once this is merged. Re-running the failed release jobs does
not help, because
workflow_dispatchand re-runs read the workflow file from the tag, which still carries the olddefinition. Dispatching
docfx_manual.ymlfrom the8.19branch withnameset to the wanted version is the waythrough, at the cost of building the docs from the branch head rather than from the tag.