# How to release six SDK packages from one commit

> Check that every port carries one version, pack and publish each registry in a matrix, and push the tags last, because Go and Packagist release from a tag.

Source: https://voxgig.com/howto/release-six-sdk-packages-from-one-commit

- Audience: api-producer
- Level: advanced
- Languages: typescript, python, go, php, ruby, lua
- Verified: 2026-11-22
- Published: 2026-11-21

## Short answer

Keep one version in a file the ports are generated from, and fail the release when any manifest disagrees with it. In sdkgen, set it through the spread in `project.aontu`, then run `package update --no-fetch` before generating, or Go and PHP keep the scaffold version. Pack the npm, PyPI, RubyGems, and LuaRocks uploads in a matrix and publish each in its own job. Push every tag after the last upload, because a tag releases Go and PHP.

---
## You will need

Node 22 or later, an sdkgen project with `ts`, `py`, `go`, `php`, `rb` and `lua` targets, and a
publisher set up on each registry. Verified 2026-11-22 against Node 22.23.5,
`@voxgig/create-sdkgen` 0.31.9, `@voxgig/sdkgen` 4.44.3 and 4.45.0, Swagger Codegen 3.0.85,
`openapi-python-client` 0.30.0, luarocks 3.8.0 and Composer 2.8.12. Nothing here publishes: each port
was packed, and a scratch repository was tagged, from one generated commit.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [changesets](https://changesets.dev/guide/beyond-npm) | The ports live in a JavaScript workspace and contributors write change files | Every non-npm port needs a private `package.json` and `privatePackages.version` to carry its version | Five of six ports are not JavaScript |
| [goreleaser](https://goreleaser.com/getting-started/quick-start/) | You also ship Go binaries, such as a CLI over the Go SDK | It starts from the latest Git tag, so the Go module is released first | The Go port is a library with no binary |
| [`openapi-python-client`](https://github.com/openapi-generators/openapi-python-client) | The Python client is the only one, or comes from its own generator | Covers Python alone, and writes `info.version` unless `package_version_override` is set | Every port must come from one generator |
| [release-please](https://github.com/googleapis/release-please/blob/main/docs/customizing.md#updating-arbitrary-files) | Conventional commits, and a release pull request per version | No Lua release type, so the rockspec needs an `extra-files` entry you configure | Nobody writes conventional commit messages |
| [sdkgen release flow](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) | One model generates all six ports into one repository | A copy refresh before Go and PHP move, and five registries the `Makefile` leaves to you | Each port has its own repository and owner |
| [Swagger Codegen](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generators-configuration/) | Five ports from free, offline generation, without Lua | One version spelled through five options, and no client for Lua in 3.x | You need Lua, or one key for every port |

Voxgig maintains sdkgen. It is one of six options here, not the recommendation.

changesets, release-please and goreleaser decide versions and run the release; they generate
nothing. The three generators decide where the version lands, which is the half that breaks
first. A release tool on top of the wrong manifests tags the wrong number with confidence.

## Set one version for every port

sdkgen keeps a version per target. The spread `&:` in `.sdk/model/project.aontu` sets all six in
one line, `main: kit: target: &: publish: version: '1.5.0'`. `generate.sh` scaffolds six targets,
adds that line, and runs `npm run generate`. `versions.mjs` then reads every place a version lives:

```bash
node versions.mjs generated/sdkgen-stale
```

```text output
generated/sdkgen-stale
  ts  ts/package.json           1.5.0
  ts  Makefile tag              1.5.0
  py  py/pyproject.toml         1.5.0
  py  Makefile tag              1.5.0
  go  go/VERSION, its tag       0.0.1
  php php/VERSION, its tag      0.0.1
  php Makefile tag              1.5.0
  rb  rb/Bookshelf_sdk.gemspec  1.5.0
  rb  Makefile tag              1.5.0
  lua lua/bookshelf.rockspec    1.5.0
  lua rockspec source tag       1.5.0
  lua Makefile tag              1.5.0
  2 problems
    go: go/VERSION, its tag says 0.0.1, the release is 1.5.0
    php: php/VERSION, its tag says 0.0.1, the release is 1.5.0
```

Go and PHP read their `VERSION` files from copies the scaffold filled in under `.sdk/tm/`, and the
run printed one warning naming both. `@voxgig/sdkgen` 4.45.0 left the same two files at 0.0.1, and
wrote the rockspec, `composer.json` and each `Makefile` byte for byte as 4.44.3 did. Run
`npx voxgig-sdkgen package update @voxgig/sdkgen --no-fetch` inside `.sdk/`, generate again, and
`generated/sdkgen-fixed` reads `every port agrees`. The workflow's first job runs the same check
against `VERSION`, so a stale file stops the release before anything is uploaded.

## Pack every upload from the same commit

`record.sh` committed the fixed project to a scratch repository and packed each port that a
registry takes as a file, reading the version back out of each artifact:

```bash
cat recorded/packed.txt
```

```text output
packed from one commit, release 1.5.0
  ts   voxgig-sdk-bookshelf-sdk-1.5.0.tgz  package/package.json: 1.5.0
  py   voxgig_sdk_bookshelf_sdk-1.5.0.tar.gz  PKG-INFO: 1.5.0
  rb   bookshelf.gem  gem specification: 1.5.0
  lua  luarocks 3.8.0
  lua  bookshelf.rockspec  lint exit 1: Expected filename in format 'name-version-revision.rockspec'.
  lua  voxgig-sdk-bookshelf-sdk-1.5.0-1.rockspec  lint exit 1: Unknown field issues_url (using rockspec format 1.0 -- adding 'rockspec_format = "3.0"' to the rockspec will fix this)
  lua  voxgig-sdk-bookshelf-sdk-1.5.0-1.rockspec  lint exit 0
  go   nothing to upload: the module is the tag go/v1.5.0
  php  nothing to upload: Packagist reads composer.json and tags from git
```

The generated rockspec failed `luarocks lint` twice. Under its own name, luarocks answered
"Expected filename in format 'name-version-revision.rockspec'". Renamed, it refused `issues_url`
until a `rockspec_format = "3.0"` line went in. The workflow writes the corrected copy. The rockspec's source
also names the tag `lua/v1.5.0`, so the uploaded rock cannot install until the tag job runs.

## Push the tags after every upload

`release.yml` runs four stages, and `check-workflow.mjs` fails it when any stage can start early.
The tag job waits on every publisher and pushes all six port tags in one atomic push, so the
remote takes every tag or none:

```yaml title="release.yml"
      - name: Push every port's tag in one atomic push
        env:
          VERSION: ${{ needs.version.outputs.version }}
        run: |
          set -euo pipefail
          tags=()
          for port in ts py go php rb lua; do
            git tag -a "$port/v$VERSION" -m "$port v$VERSION"
            tags+=("refs/tags/$port/v$VERSION")
          done
          git push --atomic origin "${tags[@]}"
```

```bash
node check-workflow.mjs
```

```text output
release.yml: 19 action uses checked against pins-ls-remote.txt
  pins, order, privileges and ports as required
```

Every action is pinned to the commit its tag resolved to through `git ls-remote`, recorded in
`pins-ls-remote.txt`. Only the tag job can write to the repository. npm and PyPI publish through
[trusted publishing](https://docs.npmjs.com/trusted-publishers/), RubyGems through
`GEM_HOST_API_KEY`, and LuaRocks through
[`luarocks upload --skip-pack`](https://github.com/luarocks/luarocks/blob/main/docs/luarocks_upload.md),
because packing would fetch a tag that does not exist yet.

PHP needs a repository of its own. Composer read no release from the monorepo:

```bash
cat recorded/composer.txt
```

```text output
Composer version 2.8.12
the monorepo, tagged php/v1.5.0, composer.json under php/
  composer show exit 1
  No valid composer.json was found
a split repository with composer.json at its root, tagged php/v1.5.0
  composer show exit 0
  versions: dev-main
```

Packagist's [about page](https://packagist.org/about) puts `composer.json` at the top of the
package's git repository. Composer's
[versions article](https://getcomposer.org/doc/articles/versions.md) reads a version from the tag
name, and a `php/v1.5.0` tag gave no version even at the root. The tag job splits `php/` into a mirror repository and tags it `v1.5.0`, which Composer read
as `v1.5.0`.

## Pass the version to Swagger Codegen and the Python generator

Swagger Codegen 3.0.85 takes the version per language. `generate.sh` ran it twice on the same
document:

```bash
node others.mjs
```

```text output
Swagger Codegen 3.0.85, --artifact-version 1.5.0 on every language
  typescript-fetch package.json                no file written
  python           setup.py VERSION            1.0.0
  go               configuration.go UserAgent  1.0.0
  php              composer.json               1.5.0
  ruby             version.rb VERSION          1.0.0
Swagger Codegen 3.0.85, each language's own option set to 1.5.0
  typescript-fetch package.json                1.5.0
  python           setup.py VERSION            1.5.0
  go               configuration.go UserAgent  1.5.0
  php              composer.json               1.5.0
  ruby             version.rb VERSION          1.5.0
openapi-python-client 0.30.0
  no config                         pyproject.toml 1.0.0
  package_version_override: 1.5.0   pyproject.toml 1.5.0
```

`--artifact-version` reached PHP alone. The five options are `npmVersion` with `npmName`,
`packageVersion` twice, `artifactVersion` and `gemVersion`, passed through `--additional-properties`,
as `config-help -l <lang>` lists them.[^1] Read all five from one `VERSION` file in the script that
runs the generator. Swagger Codegen writes `"version"` into `composer.json`, which the
[Composer documentation](https://getcomposer.org/doc/02-libraries.md) warns will conflict with tag
names, so delete it before tagging. It has no Lua client in 3.x, so the sixth port needs another tool.

`openapi-python-client` writes the document's `info.version` unless its configuration sets
[`package_version_override`](https://github.com/openapi-generators/openapi-python-client), so the
Python package follows the API's own version until you pin it.

## Check it worked

Thirteen tests read the committed generations, the recorded packs and tags, and the workflow:

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

```text output
# tests 13
# suites 0
# pass 13
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

The workflow check is given broken copies too. An action on a moving tag fails it, and so does a
tag job that skips LuaRocks or runs on `always()`. So do a publisher with `continue-on-error`, a
missing port, a publisher that tags, and a step without `set -euo pipefail`.

## When it goes wrong

Go users install a version nobody announced. The Go tag was pushed before a later upload failed,
and the [Go modules reference](https://go.dev/ref/mod#vcs-version) resolves versions from tags.
A pushed version can only be retracted in a later release. Keep every tag in the last job.

One upload fails after others succeeded. No tag has gone out, so rerun the failed jobs, and follow
[recover when one registry upload fails mid release](/howto/recover-from-a-partial-multi-registry-release)
for a registry that refuses the same version twice.

npm answers 404 to the publish. npm trusts one workflow file per package, and the scaffold's
`.sdk/admin/setup-npm-trust.sh` registers `publish-ts.yml`. Register `release.yml` in its place on
npmjs.com.

The LuaRocks upload succeeds and `luarocks install` fails. The rockspec points at `lua/v1.5.0`,
which the tag job had not pushed yet. Rerun the tag job.

The tag job fails after the PHP mirror took its tag. The mirror and the monorepo are two pushes,
which no single push can make atomic. Fix the monorepo push and rerun the job: the mirror step
finds its own tag on the same commit and skips the push, and a test runs it twice to show that.

## When not to do this

Do not lock all six to one number if each port has its own owner and schedule. Python takes a
packaging fix alone, and lockstep then tags five empty releases.

Do not rely on the generated `Makefile` as the release. sdkgen's `make deploy-<target>` pushes one
port's tag, there is no deploy for every target, and its header marks LuaRocks, Packagist, PyPI,
RubyGems and npm publishing as pending. The scaffold's `publish-ts.yml` publishes npm alone.

Swagger Codegen suits five ports from free, offline generation when nobody needs Lua.
`openapi-python-client` suits a team whose Python client is the one that matters, generated apart
from the rest.

## Related how-tos

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

- [Recover when one registry upload fails mid release](/howto/recover-from-a-partial-multi-registry-release)

- [Choose lockstep or independent versions across your SDKs](/howto/lockstep-or-independent-versions-across-sdk-languages)

- [Build a CI matrix for an SDK across six languages](/howto/sdk-ci-matrix-across-six-languages)

- [Tag a polyglot SDK repo so Go modules resolve](/howto/tag-a-polyglot-repo-for-go-modules)

## Last verified

Verified 2026-11-22 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, `@voxgig/sdkgen` 4.44.3
and 4.45.0, `@voxgig/apidef` 8.32.4, Swagger Codegen 3.0.85 on OpenJDK 21, `openapi-python-client`
0.30.0, `build` 1.6.1, RubyGems 3.5.22, luarocks 3.8.0 and Composer 2.8.12. Every output block is what
the command preceding it printed. Generation ran in `generate.sh` and the packs, tags and pins in
`record.sh`, committed under `generated/` and `recorded/`. `release.yml` was checked by script and
not run on GitHub, and no registry received an upload.

[^1]: Swagger Codegen's [configuration page](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generators-configuration/)
offers two ways to pass an option, a configuration file or `-D{optionName}={optionValue}`, and
adds that if `-D{optionName}` does not work, readers should open a ticket. Given
`-DnpmName=@example/bookshelf`, the `typescript-fetch` run here wrote no `package.json`, which
`generated/swagger-codegen/dflag` records. The same two options through `--additional-properties`
wrote one.