How-to › Release and secure packages

How to tag a polyglot SDK repo so Go modules resolve#

Tag each release twice, v1.4.0 and go/v1.4.0, in one atomic push, prove the go command resolves the module in go/, and never move a Go tag once fetched.

Audience
Library maintainer
Level
advanced
Topic
Publish to package registries
Languages
Go, TypeScript and Python
Verified

Your release job tags v1.4.0, and the npm and PyPI packages go out. go get of the module in go/ fails, because the go command reads v1.4.0 as a version of the root module, which has no package at that path. A fix moved by hand onto go/v1.4.0 later fails the checksum check of a consumer whose go.sum holds the first one and whose module cache does not.

What you get

You will end up with a release script that pushes v1.4.0 and go/v1.4.0 together, and a test that lets the go command resolve the module from real git tags with no network. This is for you if one repository holds your ts/, py/ and go/ SDKs.

Short answer

A Go module in the go/ directory of a repository is released by a tag named go/v1.4.0, not by the plain v1.4.0 your npm and PyPI jobs read. Push both from one script with git push --atomic, so the remote never holds one without the other. A wrong Go tag cannot be fixed by moving it, because go.sum and the checksum database already hold its hash, so release the next version.

You will need

Node 22 or later, Go 1.24 or later, git, and a repository with a Go module in a subdirectory. Verified 2026-11-22 against Go 1.24.7 and Go 1.25.0, git 2.43.0, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, Swagger Codegen 3.0.85, and openapi-typescript 7.13.0. The rule itself is in the Go modules reference: a module in a subdirectory takes tags prefixed with that subdirectory and a slash.1

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
GoReleaser Pro monorepoYou build Go binaries with GoReleaser and tag each directoryA Pro license, and it reads the prefixed tag rather than creating itYour Go module ships source only
One repository per languageEach language has its own team and release clockA release across languages becomes several pushes that can stop half wayOne commit must carry every language
openapi-typescript and openapi-fetchYour ts/ package is types plus a small fetch clientIt writes types and no version, so the tag scheme is yoursYou also need the Go client generated
A prefixed subdirectory tag such as go/v1.4.0One repository, one version, every languageTwo tags per release, and a script that must push both or neitherGo is the only language in the repository
The sdkgen ts/py/go output layoutsdkgen generates every port, each tagged <target>/vX.Y.Z by its MakefileNo plain tag, and go/VERSION lags a version change until package updateYour npm and PyPI jobs expect a plain tag
Swagger CodegenA Go client whose module, path, and tags you set up yourselfNo go.mod, and a git_push.sh built for one repository per clientYou want the tag written for you

Voxgig maintains sdkgen, one of six options compared here.

The prefixed tag keeps one repository and one version, at the cost of two tags that must move together. A repository per language needs plain tags only, but a release becomes several pushes. Moving the Go module to the root and the other languages down a level lets one plain v1.4.0 serve Go too, since a root module’s tags equal its versions.

Push both tags in one atomic push

tag-release.sh tags one commit twice and sends both refs in one git push --atomic, which updates all refs or none. It refuses a version Go cannot take, a go/VERSION that names another version, a tag that already exists here or on the remote, and a remote it cannot list. A refused push leaves no local tag.

if [ -f go/VERSION ] && [ "$(cat go/VERSION)" != "$version" ]; then
  echo "tag-release: go/VERSION says $(cat go/VERSION), not $version; regenerate before tagging" >&2
  exit 2
fi
for tag in "v$version" "go/v$version"; do
  if git rev-parse -q --verify "refs/tags/$tag" > /dev/null; then
    echo "tag-release: $tag already exists; a published Go version cannot be moved, so release the next version" >&2
    exit 1
  fi
  status=0 # git ls-remote exits 2 for a remote without the tag, other codes for no answer
  git ls-remote --exit-code --tags "$remote" "refs/tags/$tag" > /dev/null || status=$?
  if [ "$status" -eq 0 ]; then
    echo "tag-release: $tag already exists; a published Go version cannot be moved, so release the next version" >&2
    exit 1
  elif [ "$status" -ne 2 ]; then
    echo "tag-release: could not list the tags of $remote (git exited $status), so nothing was tagged" >&2
    exit 1
  fi
done
git tag "v$version"
git tag "go/v$version"
if ! git push --atomic "$remote" "refs/tags/v$version" "refs/tags/go/v$version"; then
  git tag -d "v$version" "go/v$version" > /dev/null
  echo "tag-release: the push was refused, so neither tag was kept" >&2
  exit 1
fi

release.yml runs it from a workflow_dispatch input, with contents: write and a full-depth checkout so the existing tags are there to check.

Let the go command resolve the tags

resolve.mjs builds a bare repository with ts/, py/ and go/, and a consumer module. With GOPROXY=direct the go command lists the repository’s tags itself. A git insteadOf rule points the address it derives from the module path at the local repository, so no request leaves the machine.

node resolve.mjs
module example.com/acme/bookshelf-sdk.git/go, in go/ beside ts/ and py/

1. only the plain tag v1.4.0 is pushed
   go get example.com/acme/bookshelf-sdk.git/go@v1.4.0: exit 1
   go: module example.com/acme/bookshelf-sdk.git@v1.4.0 found, but does not contain package example.com/acme/bookshelf-sdk.git/go

2. tag-release.sh adds go/v1.4.0 beside it
   tag-release.sh 1.4.0: exit 0, tag-release: pushed v1.4.0 and go/v1.4.0
   origin tags: go/v1.4.0 v1.4.0
   go get example.com/acme/bookshelf-sdk.git/go@v1.4.0: exit 0
   go list -m -versions: example.com/acme/bookshelf-sdk.git/go v1.4.0
   go run .: bookshelf 1.4.0

3. the same release tagged again
   tag-release.sh 1.4.0: exit 1, tag-release: v1.4.0 already exists; a published Go version cannot be moved, so release the next version

4. go/v1.4.0 moved to a fixed commit by hand, after a consumer fetched it
   the consumer's module cache: go run .: bookshelf 1.4.0
   an empty module cache and the same go.sum: go mod download: exit 1
   verifying example.com/acme/bookshelf-sdk.git/go@v1.4.0: checksum mismatch

5. the fix released as the next version instead
   tag-release.sh 1.4.1: exit 0, tag-release: pushed v1.4.1 and go/v1.4.1
   go get example.com/acme/bookshelf-sdk.git/go@v1.4.1: exit 0
   go run .: bookshelf 1.4.1

The plain tag resolved, as a version of the root module, which has no package at that path. The moved tag left two consumers with two answers: the one with a cache kept the old code, and the one without failed against its own go.sum.

Read the tags sdkgen and the generators leave

sdkgen tags every port <target>/vX.Y.Z, so the Go tag is already prefixed. sdkgen-tags.mjs reads the generated Makefile and go/Makefile at each step of generate.sh.

node sdkgen-tags.mjs
go/go.mod: module github.com/voxgig-sdk/bookshelf-sdk/go

scaffold, @voxgig/sdkgen 4.44.3
  tags: go/v0.0.1  py/v0.0.1  ts/v0.0.1
  go/VERSION 0.0.1, ts/package.json 0.0.1, py/pyproject.toml 0.0.1

publish: version: '1.4.0' for every target, then generate
  tags: go/v0.0.1  py/v1.4.0  ts/v1.4.0
  go/VERSION 0.0.1, ts/package.json 1.4.0, py/pyproject.toml 1.4.0
  WARN target go: 1 file(s) in .sdk are unchanged copies, but @voxgig/sdkgen 4.44.3 has changed since they were copied

package update @voxgig/sdkgen --no-fetch, then generate
  tags: go/v1.4.0  py/v1.4.0  ts/v1.4.0
  go/VERSION 1.4.0, ts/package.json 1.4.0, py/pyproject.toml 1.4.0

the version change on @voxgig/sdkgen 4.45.0 with @voxgig/apidef 8.33.1
  tags: go/v0.0.1  py/v1.4.0  ts/v1.4.0
  go/VERSION 0.0.1, ts/package.json 1.4.0, py/pyproject.toml 1.4.0
  WARN target go: 1 file(s) in .sdk are unchanged copies, but @voxgig/sdkgen 4.45.0 has changed since they were copied

After the version change, go/Makefile would tag go/v0.0.1 beside a 1.4.0 release, and only one WARN line says so. Run the package update it names before every release. tag-release.sh refuses to tag while go/VERSION names another version, and a test shows it. The module path is the scaffold’s own; set yours with main: kit: target: go: module: path: in the project overlay.

Swagger Codegen and openapi-typescript leave the tag to you, and npm version inside ts/ does too:

node generators.mjs
Swagger Codegen 3.0.85, -l go
  go.mod written: false, among 14 files
  go client templates in the jar: 13, named go.mod: 0
  packageVersion 1.4.0 appears in: README.md, configuration.go
  git_push.sh: git remote add origin https://github.com/${git_user_id}/${git_repo_id}.git
  git_push.sh: git push origin master 2>&1 | grep -v 'To https'
  git_push.sh lines that run git tag: 0

openapi-typescript 7.13.0
  output: one file, schema.d.ts, 170 lines; a version in it: none
npm 10.9.9, npm version 1.4.0 inside ts/ of a git repository
  printed v1.4.0; ts/package.json 1.4.0; tags created: 0; commits made: 0; git status: M ts/package.json

For Swagger Codegen, write go/go.mod yourself with the module path that ends in /go, and tag with tag-release.sh. Its git_push.sh assumes the client is the whole repository. For openapi-typescript, the version lives in ts/package.json. The npm documentation says npm version run in a git repo also creates a version commit and tag. npm 10.9.9 decides that with is.js of @npmcli/git, which looks for .git in the package’s own directory. In ts/ there is none, so it changed package.json only, and the tags come from the script.

Check it worked

The tests tag scratch repositories and resolve them with the go command, and check the records.

node --test tags.test.mjs
1..11
# tests 11
# suites 0
# pass 11
# fail 0
# cancelled 0
# skipped 0
# todo 0

One test installs a pre-receive hook that rejects go/ tags and expects the remote to end with no tags at all, which is what --atomic buys. Another pushes go/v1.5.0 from elsewhere and expects tag-release.sh 1.5.0 to refuse. A third gives git an ssh command that leaves a mark, and expects none after go get, since every address the go command tries points at the local repository.

When it goes wrong

The npm and PyPI jobs never start after the tags land. They run on a tag push, and events triggered by the GITHUB_TOKEN do not create workflow runs. Call the publish jobs from the release workflow, or push with a token of their own.

A moved go/v1.4.0 still serves the old code to the public. The GOPROXY protocol requires a proxy to serve the same content for a version every time, and the checksum database keeps a version’s bits fixed even if the author alters the tags. That part cannot run offline, so the demo shows the local half. Release go/v1.4.1, and mark 1.4.0 with a retract directive in that release.

Given 2.0.0, tag-release.sh refuses because the module path needs to end in /v2. Go requires the suffix from major version 2, so change go/go.mod first.

When not to do this

Do not keep Go in a subdirectory if Go is the only language that ships from the repository. Move the module to the root and use plain tags.

Do not let sdkgen’s generated Makefile recipes cut the release tags without a check of go/VERSION. The generated go/Makefile tags from that file, and on 4.44.3 and 4.45.0 it lagged a version change.

Do not use GoReleaser Pro for this alone. It reads a prefixed tag and builds from it, so for a module that ships source it adds a license where a script suffices. It is the better choice when you already publish Go binaries from each directory.

Last verified

Verified 2026-11-22 against Node 22.23.5, Go 1.24.7, git 2.43.0, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3 and 4.45.0, @voxgig/apidef 8.32.4 and 8.33.1, Swagger Codegen 3.0.85, openapi-typescript 7.13.0, and npm 10.9.9. resolve.mjs and the tests run the go command on each check, and generate.sh recorded the same resolve.mjs output under Go 1.24.7 and the Go 1.25.0 toolchain. The generators ran once in generate.sh, and their output is committed. The module proxy was not contacted: what it does with a moved tag is read from the Go modules reference.

Footnotes

  1. The modules reference gives its own example of the rule: the module golang.org/x/tools/gopls lives in the gopls subdirectory, so its version v0.4.0 is the tag gopls/v0.4.0 in the repository whose root path is golang.org/x/tools. The reference teaches the rule with a module of the Go project’s own, kept in a subdirectory of another. ↩︎ 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.