diff options
Diffstat (limited to 'doc/user/packages/go_proxy/index.md')
| -rw-r--r-- | doc/user/packages/go_proxy/index.md | 150 |
1 files changed, 74 insertions, 76 deletions
diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index bd3b5b49ebd..81edc3afcfd 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -4,11 +4,11 @@ group: Package info: 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 +# Go proxy for GitLab > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1. > - It's deployed behind a feature flag, disabled by default. -> - It's disabled on GitLab.com. +> - It's disabled for GitLab.com. > - It's not recommended for production use. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-the-go-proxy). > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. @@ -16,14 +16,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w With the Go proxy for GitLab, every project in GitLab can be fetched with the [Go proxy protocol](https://proxy.golang.org/). -## Prerequisites +## Enable the Go proxy -### 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](https://gitlab.com/gitlab-org/gitlab/-/issues/218083). -The Go proxy for GitLab is under development and not ready for production use, due to -[potential performance issues with large repositories](https://gitlab.com/gitlab-org/gitlab/-/issues/218083). - -It is deployed behind a feature flag that is **disabled by default**. +It's deployed behind a feature flag that is _disabled by default_. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can enable it for your instance. @@ -47,57 +45,46 @@ 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 **Packages > List** entry under your project's sidebar, verify -the following: - -1. Your GitLab administrator has - [enabled support for the Package Registry](../../../administration/packages/index.md). -1. The Package Registry is [enabled for your project](../index.md). - NOTE: **Note:** -GitLab does not currently display Go modules in the **Packages Registry** of a project. -Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213770) for details. +Even if it's enabled, GitLab doesn't display Go modules in the **Package Registry**. +Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213770) 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: +To use GitLab as a Go proxy, you must be using Go 1.13 or later. -- Project - can fetch modules defined by a project - `/api/v4/projects/:id/packages/go` +The available proxy endpoint is for fetching modules by 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](#set-environment-variables). For -details on configuring `GOPROXY`, see [Dependency Management in Go > -Proxies](../../../development/go_guide/dependencies.md#proxies). +To fetch Go modules from GitLab, add the project-specific endpoint to `GOPROXY`. -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 queries the endpoint and falls back to the default behavior: ```shell -go env -w GOPROXY='https://gitlab.com/api/v4/projects/1234/packages/go,https://proxy.golang.org,direct' +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 as follows: +With this configuration, Go fetches dependencies in this order: -1. Attempt to fetch from the project-specific Go proxy. -1. Attempt to fetch from [proxy.golang.org](https://proxy.golang.org). -1. Fetch directly with version control system operations (such as `git clone`, +1. Go attempts to fetch from the project-specific Go proxy. +1. Go attempts to fetch from [proxy.golang.org](https://proxy.golang.org). +1. Go fetches directly with version control system operations (like `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. +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](#set-environment-variables). + +For details about configuring `GOPROXY`, see +[Dependency Management in Go > Proxies](../../../development/go_guide/dependencies.md#proxies). ## 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. +`go` doesn't support transmitting credentials over insecure connections. The +following steps work only if GitLab is configured for HTTPS: 1. Configure Go to include HTTP basic authentication credentials when fetching from the Go proxy for GitLab. @@ -107,31 +94,38 @@ steps below work only if GitLab is configured for HTTPS. ### Enable request authentication Create a [personal access token](../../profile/personal_access_tokens.md) with -the `api` or `read_api` scope and add it to -[`~/.netrc`](https://ec.haxx.se/usingcurl/usingcurl-netrc): +the scope set to `api` or `read_api`. -```netrc +Open your [`~/.netrc`](https://ec.haxx.se/usingcurl/usingcurl-netrc) file +and add the following text. Replace the variables in `< >` with your values. + +```plaintext 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. +- `<url>`: The GitLab URL, for example `gitlab.com`. +- `<username>`: Your username. +- `<token>`: Your personal access token. ### 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](#set-environment-variables). For more -details on disabling this feature of Go, see [Dependency Management in Go > -Checksums](../../../development/go_guide/dependencies.md#checksums). +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](#set-environment-variables). For more details about +disabling this feature of Go, see +[Dependency Management in Go > Checksums](../../../development/go_guide/dependencies.md#checksums). -For example, to disable checksum queries for `gitlab.com/my/project`, set `GONOSUMDB`: +For example, to disable checksum queries for `gitlab.com/my/project`, set +`GONOSUMDB`: ```shell go env -w GONOSUMDB='gitlab.com/my/project,<previous value>' @@ -139,32 +133,36 @@ 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: +If you're unfamiliar with managing dependencies in Go, or Go in general, review +the following documentation: - [Dependency Management in Go](../../../development/go_guide/dependencies.md) - [Go Modules Reference](https://golang.org/ref/mod) -- [Documentation (golang.org)](https://golang.org/doc/) -- [Learn (learn.go.dev)](https://learn.go.dev/) +- [Documentation (`golang.org`)](https://golang.org/doc/) +- [Learn (`learn.go.dev`)](https://learn.go.dev/) ### 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 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 but `GOPATH` 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`. +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](../../../development/go_guide/dependencies.md#versioning) for more -details on what constitutes a valid module or module version. +SVN, and Mercurial. A module is a repository that contains `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](../../../development/go_guide/dependencies.md#versioning) +for more details about what constitutes a valid module or module version. |