Trigger ref docs on a docs release, and generate both 0.x and 1.x - #525
Merged
Merged
Conversation
Follows agentgateway/website and kgateway-dev/kgateway.dev, which each publish a "Docs for vX" release and read its tag rather than wiring cross-repo credentials. Publishing a release here tagged v1.0.0-alpha2 now regenerates the docs at that kagent release. Also fixes the no-input fallback, which was wrong independently of the trigger. It used `gh release view`, which returns the release GitHub marks Latest -- the newest stable release, correctly a 0.10.x one, since 0.10.x is the stable line and 1.0 still ships as alpha prereleases. That is a different question than this job asks: these are the 1.x pages, so the fallback now takes the newest 1.x release. kagent published v0.10.2 on 2026-09-23, a day after v1.0.0-alpha2, which is what surfaced it. Verified all three paths against the live API: a docs release tag, an explicit version, and no input. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Docs preview
Both are uploaded Worker versions and serve no production traffic. |
0.10.x is the stable line and still takes patches -- v0.10.2 landed on 2026-09-23 -- so calling it frozen and regenerating it by hand was the premise that let its pages drift. Publishing a docs release tagged v0.10.2 now regenerates 0.x the same way v1.0.0-alphaN regenerates 1.x. The resolve job derives the line from the version. A new "Resolve line configuration" step holds everything the two lines disagree on, which is more than a path segment: the section is resources/ in 0.x and reference/ in 1.x, 0.x ships v1alpha2 where 1.x ships v1alpha3, the frontmatter differs down to linkTitle and weight, 0.x takes no --link-prefix because it is not rebased into the enterprise hub, and 0.x predates Harness so it pins no runtime image. Keeping the lines from overwriting each other took two changes: - max-kube.md is now version-split. It was the only flat conref read by pages of both lines, so a 0.x run would have published the 0.10.x Kubernetes version onto the 1.x pages. The committed public/ copy that nothing outside this workflow reads is left at the 1.x value, and the generator now takes the version straight from the resolved tree rather than round-tripping through it. - The version-split writes go through one helper that writes only the running line's span and refuses to continue if any other span moved. That assertion replaces the two hand-written 1.x-only surgeries. The conrefs that are still flat -- kmcp, kagent-tools, the runtime images -- are read only by 1.x pages, so a 0.x run skips them rather than filling them from the 0.10.x tree. The kmcp generation steps, runtime image resolution and the kmcp half of the CLI audit are gated the same way. The generated PR gets a per-line branch, so a 0.x run cannot force-push over an open 1.x regeneration. Verified by running the rendered steps: the conref step for both lines against copies of the real files (each writes its own span, leaves the other, gains no trailing newline, and refuses a line with no span), the line configuration step for both (every path it emits exists), and the resolve step against the live API. Generated the 0.x API reference from the v0.10.2 tag through crd-ref-docs and the real post-processing: 86 types, exactly the set the committed 0.x page already has, plus 46 required-field markers. bash -n parses every step. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Rachael-Graham
changed the title
Nadine2016
approved these changes
Sep 23, 2026
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.
Follow-up to #500, which merged with the cross-repo trigger before we settled on the peer pattern.
Trigger.
repository_dispatch→release: types: [published]. Publishing a release here taggedv1.0.0-alpha2regenerates the docs at that kagent release — whatagentgateway/websiteandkgateway.devalready do. kagent-dev/kagent#2900 is closed in favor of it.Both lines. 0.10.x is the stable line and still takes patches (v0.10.2 landed 2026-09-23), so it's generated here rather than by hand. A docs release tagged
v0.10.2regenerates 0.x.Worth a close look:
max-kube.mdwas the only flat conref read by pages of both lines, so a 0.x run would have published the 0.10.x Kubernetes version onto the 1.x pages. It's now version-split, and both split conrefs go through one helper that writes only the running line's span and fails if any other span moved.Also fixes the no-input fallback, which took GitHub's "Latest" — correctly a 0.10.x release, wrong for these pages.
Merge before cutting a docs release:
releaseworkflows run from the default branch, so the trigger can't fire until this lands.