# 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.

Source: https://voxgig.com/howto/tag-a-polyglot-repo-for-go-modules

- Audience: library-maintainer
- Level: advanced
- Languages: go, typescript, python
- Verified: 2026-11-22
- Published: 2026-11-22

## 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](https://go.dev/ref/mod#vcs-version): 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](https://goreleaser.com/customization/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](https://go.dev/ref/mod#vcs-dir) | 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](https://openapi-ts.dev/cli) | 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](https://go.dev/ref/mod#vcs-version) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) | 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](https://github.com/swagger-api/swagger-codegen/blob/3.0.0/README.md) | 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`](https://git-scm.com/docs/git-push), 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.

```bash title="tag-release.sh"
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.

```bash
node resolve.mjs
```

```text output
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`.

```bash
node sdkgen-tags.mjs
```

```text output
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:

```bash
node generators.mjs
```

```text output
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](https://docs.npmjs.com/cli/v10/commands/npm-version/) says `npm version` run in a git
repo also creates a version commit and tag. npm 10.9.9 decides that with
[`is.js`](https://github.com/npm/git/blob/main/lib/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.

```bash
node --test tags.test.mjs
```

```text output
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`](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow)
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](https://go.dev/ref/mod#goproxy-protocol)
requires a proxy to serve the same content for a version every time, and the [checksum
database](https://go.dev/ref/mod#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](https://go.dev/ref/mod#go-mod-file-retract) in that release.

Given 2.0.0, `tag-release.sh` refuses because the module path needs to end in `/v2`. Go [requires the
suffix](https://go.dev/ref/mod#major-version-suffixes) 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

- [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)

- [Make a Go client reference render correctly on pkg.go.dev](/howto/render-a-go-reference-on-pkg-go-dev)

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

- [Release six SDK packages from one commit](/howto/release-six-sdk-packages-from-one-commit)

## 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.

[^1]: The modules reference gives its own [example](https://go.dev/ref/mod#vcs-version) 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.