How-to › Release and secure packages

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.

Audience
API producer
Level
advanced
Topic
Publish to package registries
Languages
TypeScript, Python, Go, PHP, Ruby and Lua
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
changesetsThe ports live in a JavaScript workspace and contributors write change filesEvery non-npm port needs a private package.json and privatePackages.version to carry its versionFive of six ports are not JavaScript
goreleaserYou also ship Go binaries, such as a CLI over the Go SDKIt starts from the latest Git tag, so the Go module is released firstThe Go port is a library with no binary
openapi-python-clientThe Python client is the only one, or comes from its own generatorCovers Python alone, and writes info.version unless package_version_override is setEvery port must come from one generator
release-pleaseConventional commits, and a release pull request per versionNo Lua release type, so the rockspec needs an extra-files entry you configureNobody writes conventional commit messages
sdkgen release flowOne model generates all six ports into one repositoryA copy refresh before Go and PHP move, and five registries the Makefile leaves to youEach port has its own repository and owner
Swagger CodegenFive ports from free, offline generation, without LuaOne version spelled through five options, and no client for Lua in 3.xYou 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.

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

  1. 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, the typescript-fetch run here wrote no package.json, which generated/swagger-codegen/dflag records. The same two options through --additional-properties wrote one. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.