6.7 KiB
| stage | group | info |
|---|---|---|
| Package | Package | To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers |
GitLab Go Proxy
- Introduced in GitLab Premium 13.1.
- It's deployed behind a feature flag, disabled by default.
- It's disabled on GitLab.com.
- It's not recommended for production use.
- To use it in GitLab self-managed instances, ask a GitLab administrator to enable it.
- Moved to GitLab Core in 13.3.
With the Go proxy for GitLab, every project in GitLab can be fetched with the Go proxy protocol.
Prerequisites
Enable the Go proxy
The Go proxy for GitLab is under development and not ready for production use, due to potential performance issues with large repositories.
It is 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))
Enable the Package Registry
The Package Registry is enabled for new projects by default. If you cannot find the {package} Packages > List entry under your project's sidebar, verify the following:
- Your GitLab administrator has enabled support for the Package Registry.
- The Package Registry is enabled for your project.
NOTE: Note: GitLab does not currently display Go modules in the Packages Registry of a project. Follow this issue for details.
Add GitLab as a Go proxy
NOTE: Note: To use a Go proxy, you must be using Go 1.13 or later.
The available proxy endpoints are:
- Project - can fetch modules defined by a project -
/api/v4/projects/:id/packages/go
To use the Go proxy for GitLab to fetch Go modules from GitLab, add the
appropriate proxy endpoint to GOPROXY. For details on setting Go environment
variables, see Set environment variables. For
details on configuring GOPROXY, see Dependency Management in Go >
Proxies.
For example, adding the project-specific endpoint to GOPROXY will tell Go
to initially query that endpoint and fall back to the default behavior:
go env -w GOPROXY='https://gitlab.com/api/v4/projects/1234/packages/go,https://proxy.golang.org,direct'
With this configuration, Go fetches dependencies as follows:
- Attempt to fetch from the project-specific Go proxy.
- Attempt to fetch from proxy.golang.org.
- Fetch directly with version control system operations (such as
git clone,svn checkout, and so on).
If GOPROXY is not specified, Go follows steps 2 and 3, which corresponds to
setting GOPROXY to https://proxy.golang.org,direct. If GOPROXY only
contains the project-specific endpoint, Go will only query that endpoint.
Fetch modules from private projects
go does not support transmitting credentials over insecure connections. The
steps below 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 api or read_api scope and add it to
~/.netrc:
machine <url> login <username> password <token>
<url> should be the URL of the GitLab instance, for example gitlab.com.
<username> and <token> should be your username and the personal access
token, respectively.
Disable checksum database queries
When downloading dependencies, by default Go 1.13 and later validate fetched
sources against the checksum database sum.golang.org. If the checksum of the
fetched sources does not match the checksum from the database, Go will not build
the dependency. This causes private modules to fail to build, as
sum.golang.org cannot fetch the source of private modules and thus cannot
provide a checksum. To resolve this issue, GONOSUMDB should be set to a
comma-separated list of private projects. For details on setting Go environment
variables, see Set environment variables. For more
details on 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 are unfamiliar with managing dependencies in Go, or Go in general, consider reviewing the following documentation:
Set environment variables
Go uses environment variables to control various features. These can be managed
in all the usual ways, but Go 1.14 will read and write Go environment variables
from and to a special Go environment file, ~/.go/env by default. If GOENV is
set to a file, Go will read and write that file instead. If GOENV is not set
but GOPATH is set, Go will read and write $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, Mercurial, and so on. A module is a repository containing go.mod and Go
files. Module versions are defined by 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 on what constitutes a valid module or module version.