Edit This Page

This tutorial takes a small Go module to a release in your Repsy Open Source Go repository, and explains the rules Repsy applies to an upload and what each refusal looks like. It complements Publishing a Go Module, which shows the same upload in short.

Go has no publish command. A Go repository is a module proxy that you fill yourself: you build the zip archive of a version of your module, and you upload it with one PUT request. Repsy reads the go.mod out of the zip, stores the zip, the go.mod and a small .info file, and serves them to the go command afterwards.

Prerequisites

• A Go repository on your Repsy Open Source instance, see Creating a Private Go Module Registry. The examples use the address https://<your-repsy-host>/<repo-name>. There is no username in the address, and https://<your-repsy-host> stands for the address of the package protocol port of your instance, for example http://localhost:9090 for a local start.
• The go command and curl. The second way to build the zip, below, also needs git, tar and zip.
• A credential: your username and password, or a deploy token. A deploy token goes into the password field and needs the Read/Write access type to publish; the username can be any non-empty value. Uploading always needs credentials, also to a public repository.

mkdir hello && cd hello
go mod init example.com/hello

package hello

// Greeting is what the module says.
func Greeting() string {
	return "Hello from Repsy"
}

git init && git add . && git commit -m "First release"
git tag v1.0.0

mkdir ~/modzip && cd ~/modzip
go mod init modzip

// Command modzip writes the module zip that the go command expects.
//
// Usage: modzip <module-path> <version> <module-dir> <output.zip>
package main

import (
	"fmt"
	"os"

	"golang.org/x/mod/module"
	"golang.org/x/mod/zip"
)

func main() {
	if len(os.Args) != 5 {
		fmt.Fprintln(os.Stderr, "usage: modzip <module-path> <version> <module-dir> <output.zip>")
		os.Exit(2)
	}
	modulePath, version, dir, output := os.Args[1], os.Args[2], os.Args[3], os.Args[4]

	out, err := os.Create(output)
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
	defer out.Close()

	if err := zip.CreateFromDir(out, module.Version{Path: modulePath, Version: version}, dir); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

go mod tidy && go build -o modzip .
./modzip example.com/hello v1.0.0 /path/to/hello /path/to/hello-module.zip

unzip -l /path/to/hello-module.zip

example.com/[email protected]/go.mod
example.com/[email protected]/hello.go

MODULE_PATH=example.com/hello
VERSION=v1.0.0
STAGING=$(mktemp -d)
mkdir -p "${STAGING}/${MODULE_PATH}@${VERSION}"
git archive "${VERSION}" | tar -x -C "${STAGING}/${MODULE_PATH}@${VERSION}"
(cd "${STAGING}" && zip -q -r -D "${OLDPWD}/module.zip" "${MODULE_PATH}@${VERSION}")

MODULE_PATH=example.com/hello
VERSION=v1.0.0

curl --fail-with-body -sS \
  -u <username>:<password-or-token> \
  -T module.zip \
  -H "Content-Sha256: $(sha256sum module.zip | cut -d' ' -f1)" \
  "https://<your-repsy-host>/<repo-name>/${MODULE_PATH}/@v/${VERSION}.zip"

BASE="https://<your-repsy-host>/<repo-name>/${MODULE_PATH}/@v"

curl -u <username>:<password-or-token> "$BASE/list"
curl -u <username>:<password-or-token> "$BASE/${VERSION}.info"
curl -u <username>:<password-or-token> "$BASE/${VERSION}.mod"

What Repsy Checks on Upload

A refused upload changes nothing in the repository: no file is stored and no version appears. An upload has to pass all of these checks:

1. Credentials. A user account can upload to every repository of the instance. A deploy token can upload to its own repository when its access type is Read/Write. A Read Only token, an expired or revoked token, a token of another repository and missing credentials are all refused with 401, and Repsy asks for HTTP Basic credentials. Nobody can upload anonymously, not even to a public repository.

2. The module path and the version in the address. The module path can have up to 512 characters and the version up to 100. The version has to be a semantic version with a leading v: v<major>.<minor>.<patch>, with an optional -<pre-release> and an optional +<build>, and without leading zeros in the numbers. Repsy checks these before it reads the body of the request.

   Accepted as a version	Refused as a version
   v1.0.0	1.0.0 (no v)
   v1.2.3-rc.1, v1.0.0-beta	v1.2 and v1 (not three numbers)
   v0.0.0-20260115103000-0123456789ab (a pseudo-version)	v01.2.3 (a leading zero)
   v0.1.0	latest, main and banana

3. The size. The zip file can be as large as GO_MAX_MODULE_ZIP_SIZE allows. The default, 500MB, is 524,288,000 bytes, that is 500 MiB. A client that announces a larger file is refused before the body is read, and so is an upload that grows past the limit while Repsy reads it, such as a chunked one. What the zip unpacks to has a limit of its own, 500 MiB in total and 100,000 files, and so has its go.mod, 16 MiB. An administrator changes the first limit with the variable, see the Configuration Reference.

4. The digest. When the request has a Content-Sha256 header, Repsy calculates the SHA-256 digest of the body and compares it. Without the header, nothing is compared.

5. The go.mod. The zip has to contain the file <module-path>@<version>/go.mod, with the module path and the version spelled as in the address, capital letters included. The file cannot be empty and needs a module line. The module path on that line has to be the module path of the address, and its first element has to contain a dot: example.com/hello is fine, hello and localhost/hello are not.

6. The version is new. See Versions Cannot Be Overwritten.

Repsy looks at the go.mod and at nothing else in the zip. The go command checks the zip as a whole when it downloads it, and refuses one that has files outside <module-path>@<version>/ with an error such as zip for example.com/[email protected] has unexpected file stray.go. Repsy has stored such a zip by then, and a version cannot be replaced, so build the zip with one of the routes above and look at it with unzip -l before you upload it.

Some rules of Go itself are not checked by Repsy, and a module that breaks them cannot be used. A module with a version v2.0.0 or higher has to end its module path with /v2 (or the number of its major version), in the go.mod, the address and the zip. The program above refuses to build a zip that has the wrong suffix. Repsy does not.

A module path is case sensitive: example.com/Hello and example.com/hello are two modules, with their own versions.

Versions Cannot Be Overwritten

Repsy never replaces a version of a Go module. Uploading a version that already exists is refused with 409 and this body, whatever the settings of the repository:

HTTP/1.1 409

{"msgId":"goModuleVersionAlreadyExists","type":"ERROR", ...}

Nothing changes: the stored zip, go.mod and .info stay as they were. A Go repository has no Package Override setting, and the Deny and Allow of the other formats do not exist here.

Publish a new version instead. This is a rule of Go’s ecosystem as much as of Repsy: the go command writes the checksum of every module it downloads into go.sum, and it refuses to use a file that no longer matches. Repsy has no checksum database to tell your users that you replaced a version on purpose. An administrator can delete a version in the web UI and upload it again, and the upload then succeeds, but everybody who had downloaded the old version gets an error like this one until they remove the entry from go.sum and clear their module cache:

verifying example.com/[email protected]: checksum mismatch

SECURITY ERROR
This download does NOT match an earlier download recorded in go.sum.

See Deleting Go Module Versions.

Troubleshooting

Repsy sends the identifier of the error and a message in a JSON body, which curl --fail-with-body prints:

{"msgId":"goModModulePathMismatch","type":"ERROR", ..., "text":"The go.mod module directive does not match the module path in the URL."}

The next step is to install the module with the go command.

Installing a Go Module from Registry Using Go Modules from Repsy

Was this page helpful?

Yes No