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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| GoReleaser Pro monorepo | You build Go binaries with GoReleaser and tag each directory | A Pro license, and it reads the prefixed tag rather than creating it | Your Go module ships source only |
| One repository per language | Each language has its own team and release clock | A release across languages becomes several pushes that can stop half way | One commit must carry every language |
| openapi-typescript and openapi-fetch | Your ts/ package is types plus a small fetch client | It writes types and no version, so the tag scheme is yours | You also need the Go client generated |
| A prefixed subdirectory tag such as go/v1.4.0 | One repository, one version, every language | Two tags per release, and a script that must push both or neither | Go is the only language in the repository |
| The sdkgen ts/py/go output layout | sdkgen generates every port, each tagged <target>/vX.Y.Z by its Makefile | No plain tag, and go/VERSION lags a version change until package update | Your npm and PyPI jobs expect a plain tag |
| Swagger Codegen | A Go client whose module, path, and tags you set up yourself | No go.mod, and a git_push.sh built for one repository per client | You 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.
Related how-tos
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
-
The modules reference gives its own example of the rule: the module
golang.org/x/tools/goplslives in thegoplssubdirectory, so its version v0.4.0 is the taggopls/v0.4.0in the repository whose root path isgolang.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