# How to release reference docs and the SDK from one tag

> Build the package and the reference site from one tag, check that both name the tag's version, and deploy the site only once the registry lists the package.

Source: https://voxgig.com/howto/release-reference-docs-with-the-sdk

- Audience: library-maintainer
- Level: intermediate
- Languages: typescript, python, go
- Verified: 2026-11-22
- Published: 2026-11-21

## 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](https://github.com/oapi-codegen/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](https://openapi-generator.tech/docs/generators/python/) | 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](https://docs.readthedocs.com/platform/stable/automation-rules.html) | 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](https://github.com/voxgig/docgen) | 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](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows) | 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](https://docs.readthedocs.com/platform/stable/api/v3.html) 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`:

```text title="records/docgen-workflow.txt"
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](https://github.com/voxgig/docgen) 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`:

```aontu title="release-overlay.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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) 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`:

```text title="records/install-join.txt"
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:

```bash
node release-check.mjs ts/v1.4.0-rc.1 release/rc1/package.tar.gz release/rc1/site
```

```text output
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:

```yaml title="release.yml"
      - 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](https://docs.npmjs.com/cli/v10/commands/npm-publish/) when a reader names no
version. `registry-demo.mjs` runs the wait against a stand-in registry, with a simulated clock:

```bash
node registry-demo.mjs
```

```text output
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`](https://openapi-generator.tech/docs/generators/python/), and the README prints it:

```markdown title="generated/openapi-generator/README.md"
- 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](https://openapi-generator.tech/docs/usage/) 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:

```text title="records/oapi-codegen-go-doc.txt"
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.

```bash
node --test release.test.mjs
```

```text output
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:

```bash
node release-check.mjs ts/v1.4.0-rc.2 release/rc2/package.tar.gz release/rc2/site
```

```text output
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

- [Add a docs output to an existing generated SDK project](/howto/add-a-docs-output-to-a-generated-sdk)

- [Detect a reference site drifting from its OpenAPI spec](/howto/check-a-reference-site-in-ci)

- [Release every port of a library on one version number](/howto/release-every-port-on-one-version)

- [Choose a release automation tool for an SDK repository](/howto/choose-a-release-automation-tool-for-an-sdk)

- [Generate a package README from your API description](/howto/generate-a-readme-from-an-api-description)

## 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.

[^1]: GitHub's [events reference](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows)
says a `repository_dispatch` triggers a workflow only if the workflow file exists on the default
branch, and runs it on the last commit there. Its `event_type` is limited to 100 characters. The
version therefore travels in `client_payload`, which the receiving workflow reads from the
`github.event` context.

[^2]: [pkg.go.dev's about page](https://pkg.go.dev/about) says its data is downloaded from
`proxy.golang.org` and 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 a `go get` through the proxy. Two of the three ways are requests to the proxy
itself.