The release sets 1.5.0, and npm, PyPI, and RubyGems take it. Go users get go/v0.0.1, because
go/VERSION kept the scaffold value, and the tag was pushed before the RubyGems upload failed. Go
resolves a module from its tags, so that release is live even though the gem never reached
RubyGems.
What you get
You will end up with a release workflow that refuses to start when any port disagrees with the version, publishes each registry from one commit, and pushes every tag last. This is for you if one repository generates TypeScript, Python, Go, PHP, Ruby and Lua clients.
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 | 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 | 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 | 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 | 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 | 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 | 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:
node versions.mjs generated/sdkgen-stale
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:
cat recorded/packed.txt
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:
- 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[@]}"
node check-workflow.mjs
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, RubyGems through
GEM_HOST_API_KEY, and LuaRocks through
luarocks upload --skip-pack,
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:
cat recorded/composer.txt
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 puts composer.json at the top of the
package’s git repository. Composer’s
versions article 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:
node others.mjs
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 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, 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:
node --test release.test.mjs
# 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 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 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
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.
Footnotes
-
Swagger Codegen’s configuration page 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, thetypescript-fetchrun here wrote nopackage.json, whichgenerated/swagger-codegen/dflagrecords. The same two options through--additional-propertieswrote one. ↩︎ Back to text