Go proxy for GitLab
Offering: GitLab.com, Self-managed, GitLab Dedicated
Status: Experiment
- Introduced in GitLab 13.1.
- It’s deployed behind a feature flag, disabled by default.
- It’s disabled for GitLab.com.
- To use it in GitLab self-managed instances, ask a GitLab administrator to enable it.
- Moved from GitLab Premium to GitLab Free in 13.3.
With the Go proxy for GitLab, every project in GitLab can be fetched with the Go proxy protocol.
For documentation of the specific API endpoints that the Go Proxy uses, see the Go Proxy API documentation.
Enable the Go proxy
The Go proxy for GitLab is under development, and isn’t ready for production use due to potential performance issues with large repositories.
It’s deployed behind a feature flag that is disabled by default.
GitLab administrators with access to the GitLab Rails console can enable it for your instance.
To enable it:
Feature.enable(:go_proxy) # or
To disable it:
Feature.disable(:go_proxy)
To enable or disable it for specific projects:
Feature.enable(:go_proxy, Project.find(1))
Feature.disable(:go_proxy, Project.find(2))
Add GitLab as a Go proxy
To use GitLab as a Go proxy, you must be using Go 1.13 or later.
The available proxy endpoint is for fetching modules by project: /api/v4/projects/:id/packages/go
To fetch Go modules from GitLab, add the project-specific endpoint to GOPROXY
.
Go queries the endpoint and falls back to the default behavior:
go env -w GOPROXY='https://gitlab.example.com/api/v4/projects/1234/packages/go,https://proxy.golang.org,direct'
With this configuration, Go fetches dependencies in this order:
- Go attempts to fetch from the project-specific Go proxy.
- Go attempts to fetch from
proxy.golang.org
. - Go fetches directly with version control system operations (like
git clone
,svn checkout
, and so on).
If GOPROXY
isn’t specified, Go follows steps 2 and 3, which corresponds to
setting GOPROXY
to https://proxy.golang.org,direct
. If GOPROXY
contains only the project-specific endpoint, Go queries only that endpoint.
For details about how to set Go environment variables, see Set environment variables.
For details about configuring GOPROXY
, see
Dependency Management in Go > Proxies.
Fetch modules from private projects
go
doesn’t support transmitting credentials over insecure connections. The
following steps work only if GitLab is configured for HTTPS:
- Configure Go to include HTTP basic authentication credentials when fetching from the Go proxy for GitLab.
- Configure Go to skip downloading of checksums for private GitLab projects from the public checksum database.
Enable request authentication
Create a personal access token with
the scope set to api
or read_api
.
Open your ~/.netrc
file
and add the following text. Replace the variables in < >
with your values.
NETRC
, Go uses its value
as a filename and ignores ~/.netrc
. If you intend to use ~/.netrc
in
the GitLab CI do not use NETRC
as an environment variable name.machine <url> login <username> password <token>
-
<url>
: The GitLab URL, for examplegitlab.com
. -
<username>
: Your username. -
<token>
: Your personal access token.
Disable checksum database queries
When downloading dependencies with Go 1.13 and later, fetched sources are
validated against the checksum database sum.golang.org
.
If the checksum of the fetched sources doesn’t match the checksum from the database, Go doesn’t build the dependency.
Private modules fail to build because sum.golang.org
can’t fetch the source
of private modules, and so it cannot provide a checksum.
To resolve this issue, set GONOSUMDB
to a comma-separated list of private
projects. For details about setting Go environment variables, see
Set environment variables. For more details about
disabling this feature of Go, see
Dependency Management in Go > Checksums.
For example, to disable checksum queries for gitlab.com/my/project
, set
GONOSUMDB
:
go env -w GONOSUMDB='gitlab.com/my/project,<previous value>'
Working with Go
If you’re unfamiliar with managing dependencies in Go, or Go in general, review the following documentation:
Set environment variables
Go uses environment variables to control various features. You can manage these
variables in all the usual ways. However, Go 1.14 reads and writes Go
environment variables to and from a special Go environment file, ~/.go/env
by
default.
- If
GOENV
is set to a file, Go reads and writes to and from that file instead. - If
GOENV
is not set butGOPATH
is set, Go reads and writes$GOPATH/env
.
Go environment variables can be read with go env <var>
and, in Go 1.14 and
later, can be written with go env -w <var>=<value>
. For example,
go env GOPATH
or go env -w GOPATH=/go
.
Release a module
Go modules and module versions are defined by source repositories, such as Git,
SVN, and Mercurial. A module is a repository that contains go.mod
and Go
files. Module versions are defined by version control system (VCS) tags.
To publish a module, push go.mod
and source files to a VCS repository. To
publish a module version, push a VCS tag.
See Dependency Management in Go > Versioning for more details about what constitutes a valid module or module version.