Your reference site deploys whenever main moves, and the package publishes when someone tags a
release. So the site describes 1.5.0 while its npm install line still fetches 1.4.0, and on a
first release the install fails outright. When the publish job fails, the site keeps describing a
release that never shipped.
What you get
You will end up with one tag that publishes the package and then its reference site, and a check that both carry the tag’s version. This is for you if you keep generated docs in the SDK repository.
Short answer
In an sdkgen project, turn on docgen’s github-pages edition, set doc.ci.active to false so the
site stops deploying on every push to main, and give the site an install line with the release
version. A workflow on the ts/v* tag packs the package, stages the site, checks that both name the
tag’s version, publishes to npm, waits until npm lists that version, and deploys the site last.
You will need
Node 22 or later, an sdkgen project with a ts target, and a tag driven release workflow. GitHub
Pages with GitHub Actions as its source, and an npm token stored as a CI secret. The sample runs
offline against a packed package and a staged site from one generation, listed in its README.md.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| oapi-codegen | A Go client whose reference is pkg.go.dev, rendered from the tagged module | No site of your own, and the page carries only the comments the generator wrote | Readers need guides and examples beside the reference |
| OpenAPI Generator | You want the package version printed in the generated docs with no overlay | Markdown docs with an install line that points at a placeholder git URL | You want a site about the client, since its html2 page documents the HTTP API |
| Read the Docs | Sphinx or MkDocs guides that should build one version per tag | Its webhook builds when the tag arrives, before npm has the package, unless CI triggers the build | Your docs are generated from the SDK model, not written in Sphinx or MkDocs |
| sdkgen | The site comes from the same model as the SDK, in the same repository | A longer release job, and a docs failure that blocks the package | Docs and code have separate owners and calendars |
| Separate docs repository | A docs team owns the site and builds on a repository_dispatch | A token with write access to another repository, and the version carried in a payload | One team owns both, and one tag should decide both |
Voxgig maintains sdkgen. It is one of five options here, not the recommendation.
Keeping the site in the SDK repository keeps it in step with the code, and a broken page then stops a package release. A separate repository decouples the two at the price of a cross-repository token, and its workflow runs on the default branch, not on your tag.1 Read the Docs builds from its own webhook with no workflow, so by default nothing makes it wait for npm. Its API can trigger the build from a job that runs after the publish.
Take the site’s deploy off main
A scaffold writes docgen’s own workflow, .github/workflows/docgen.yml. With the github-pages
edition on, it deploys the site from main:
5: branches: ['main']
43: run: echo "path=$(node .sdk/node_modules/@voxgig/docgen/bin/voxgig-docgen stage github-pages)" >> "$GITHUB_OUTPUT"
54: if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
The docgen README says to use ci.active: false to manage that
workflow separately. A docs add command does not exist in sdkgen 4.44.3, which answers
Unknown action: docs, so the overlay switches the edition on. These lines go at the end of .sdk/model/project.aontu:
main: kit: doc: edition: 'github-pages': active: true
main: kit: doc: ci: active: false
main: kit: target: ts: publish: registry: state: 'active'
main: kit: target: ts: publish: version: '1.4.0-rc.1'
main: kit: doc: target: ts: install: 'npm install @voxgig-sdk/bookshelf-sdk@1.4.0-rc.1'
After npm run generate, docgen.yml is gone and ci.yml and publish-ts.yml remain. The
registry state decides the site’s install section. At the default it reads
Install Not published. Build from the ts directory., and at active it prints an install
command, as sdkgen’s
model reference describes for
publish.registry.state. The generated command names no version, and aontu will not build one
from publish.version, because docgen types the field *'' | string:
aontu 0.76.3, the install line joined to publish.version: npm run generate exit 1
[aontu/empty]: Cannot unify values at path $.main.kit.doc.target.ts.install
aontu-join.aontu: [aontu/empty]: Cannot unify values at path $.a.install
aontu-join.aontu without the type: "install": "npm install @voxgig-sdk/bookshelf-sdk@1.4.0-rc.1"
So the last overlay line writes the version a second time, and the next step catches the two disagreeing.
Check the tag, the package and the site
generate.sh packed ts/, staged the site with voxgig-docgen stage github-pages, committed the
project to a scratch repository and tagged it ts/v1.4.0-rc.1. release-check.mjs reads the
version from each of the three:
node release-check.mjs ts/v1.4.0-rc.1 release/rc1/package.tar.gz release/rc1/site
tag 1.4.0-rc.1 ts/v1.4.0-rc.1
package 1.4.0-rc.1 @voxgig-sdk/bookshelf-sdk
site 1.4.0-rc.1 assets/search.js npm install @voxgig-sdk/bookshelf-sdk@1.4.0-rc.1
site 1.4.0-rc.1 sdks/ts.html npm install @voxgig-sdk/bookshelf-sdk@1.4.0-rc.1
one version: 1.4.0-rc.1
It reads package/package.json out of the tarball, so it checks what npm will receive rather than
the working tree. It reads every page and script of the site, because the search index carries
the install line too. It exits 1 on a mismatch and 2 on a missing site or package.
Publish, wait for npm, then deploy
release.yml runs the check in its build job, then publishes and deploys in two more jobs. The
docs job needs publish, and publish does not finish until npm lists the version:
- name: Publish the package
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
DIST_TAG: ${{ needs.build.outputs.dist-tag }}
run: npm publish package.tar.gz --access public --tag "$DIST_TAG"
- name: Wait until npm lists the version
env:
VERSION: ${{ needs.build.outputs.version }}
run: node scripts/wait-for-registry.mjs https://registry.npmjs.org @voxgig-sdk/bookshelf-sdk "$VERSION" 600
docs:
needs: [build, publish]
A version with a hyphen goes out under the next dist-tag, because npm installs the
latest tag when a reader names no
version. registry-demo.mjs runs the wait against a stand-in registry, with a simulated clock:
node registry-demo.mjs
the package arrives during the wait
t= 0s poll 1: 404
t=10s poll 2: 404
t=20s poll 3: 200, 1.4.0-rc.1 not listed yet
t=30s poll 4: 1.4.0-rc.1 listed
deploy the docs
the publish never lands
t= 0s poll 1: 404
t=10s poll 2: 404
t=20s poll 3: 404
t=30s poll 4: 404
t=40s poll 5: 404
t=50s poll 6: 404
fail the job, the docs stay on the last release
Poll 3 is the case a status check misses: the package exists, but the version the site names is still missing from it.
Get the same guarantee from OpenAPI Generator and oapi-codegen
OpenAPI Generator writes its docs in the same run as the client: a README.md and one Markdown page
per API and model. The python generator takes the version as
packageVersion, and the README prints it:
- API version: 1.0.0
- Package version: 1.4.0rc1
- Generator version: 7.27.0
pyproject.toml carries the same 1.4.0rc1, so a check reads one value from two files the
generator wrote. The API pages under docs/ carry no version, and the README installs from
git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git, a placeholder. The generator’s
usage page lists --git-user-id and --git-repo-id
among its options. The same jar’s html2 generator writes a one-page HTML reference in the same
job, but that page shows info.version, 1.0.0, and not the package version. Host either yourself,
and the publish-then-deploy order of release.yml still applies.
oapi-codegen generates no documentation. Its reference is pkg.go.dev, which downloads its data from
proxy.golang.org and so renders a version only after the module proxy has it.2 The tag is the
release, which rules out the mismatch release-check.mjs looks for. go doc shows the package
comment that page starts from:
package bookshelf // import "example.com/bookshelf/bookshelf"
Package bookshelf provides primitives to interact with the openapi HTTP API.
Code generated by github.com/oapi-codegen/oapi-codegen/v2 version v2.8.2 DO NOT
EDIT.
Check it worked
The suite checks the three versions on rc1, the drift on rc2, and a tarball path split across the
ustar prefix and name fields. It tags two commits in a scratch git repository and feeds the check
the tag git describe prints. It runs the wait, and tests the workflow’s shape: every action pinned
to a commit, docs after publish, and an assignment wherever echo would hide a failure.
node --test release.test.mjs
1..29
# tests 29
# suites 0
# pass 29
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 1348.151016
When it goes wrong
The site names the previous release candidate. publish: version moved to 1.4.0-rc.2 and the
install line did not, so the package and the site disagree, and the build job stops before
anything publishes:
node release-check.mjs ts/v1.4.0-rc.2 release/rc2/package.tar.gz release/rc2/site
tag 1.4.0-rc.2 ts/v1.4.0-rc.2
package 1.4.0-rc.2 @voxgig-sdk/bookshelf-sdk
site 1.4.0-rc.1 sdks/ts.html npm install @voxgig-sdk/bookshelf-sdk@1.4.0-rc.1
mismatch: the site installs 1.4.0-rc.1, the tag says 1.4.0-rc.2
A stage step passes with an empty path. Line 43 of docgen’s own workflow writes
echo "path=$(...)". Under bash -e, that line exits 0 when the command inside it fails, so the
next step receives an empty path. release.yml assigns the output to a variable first, and a
failed command then fails the step. docgen 0.30.9, the newest on npm, writes it that way.
The docs deploy and the publish never ran. A workflow that deploys from the same job as the build,
or from main, has no way to know. Keep needs: [build, publish], and keep the wait inside the
publish job so a lost upload fails the run.
When not to do this
Do not hold the package behind the site when the docs are hand-written and change daily. A typo fix then waits for a release, and a broken link blocks a security patch.
Do not adopt the sdkgen site for a Go-only SDK. oapi-codegen’s output reaches pkg.go.dev from the tag with no workflow, and the version on that page is the module’s by construction.
Do not take OpenAPI Generator’s README for a published page. It prints the right version, but its install line is a placeholder, and the generator deploys nothing.
Do not let the version live in two places unchecked. The overlay holds it twice, and only
release-check.mjs stands between that duplication and a site that names the wrong release.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3,
@voxgig/apidef 8.32.4, @voxgig/docgen 0.30.9, OpenAPI Generator 7.27.0 and oapi-codegen v2.8.2.
Every output block is what the command preceding it printed, and each titled record is a file
generate.sh wrote. The workflow was not run on GitHub; its shape is tested. Read the Docs and the
dispatch to a separate repository are described from their documentation and were not run.
Footnotes
-
GitHub’s events reference says a
repository_dispatchtriggers a workflow only if the workflow file exists on the default branch, and runs it on the last commit there. Itsevent_typeis limited to 100 characters. The version therefore travels inclient_payload, which the receiving workflow reads from thegithub.eventcontext. ↩︎ Back to text -
pkg.go.dev’s about page says its data is downloaded from
proxy.golang.organd that the site monitors the Go Module Index for new packages. For one it has not seen, it lists three ways to ask: a button labeled Request, a request to the proxy for the module version, or ago getthrough the proxy. Two of the three ways are requests to the proxy itself. ↩︎ Back to text