Commit 0bbd1514 authored by Ethan Reesor's avatar Ethan Reesor Committed by Suzanne Selhorn

Update Go proxy docs to reference the Go guide

parent d9652a83
...@@ -18,10 +18,10 @@ Prior to this, Go did not have any well-defined mechanism for version management ...@@ -18,10 +18,10 @@ Prior to this, Go did not have any well-defined mechanism for version management
While 3rd party version management tools existed, the default Go experience had While 3rd party version management tools existed, the default Go experience had
no support for versioning. no support for versioning.
Go modules use semantic versioning. The versions of a module are defined as VCS Go modules use [semantic versioning](https://semver.org). The versions of a
tags that are valid semantic versions prefixed with `v`. For example, to release module are defined as VCS (version control system) tags that are valid semantic
version `1.0.0` of `gitlab.com/my/project`, the developer must create the Git versions prefixed with `v`. For example, to release version `1.0.0` of
tag `v1.0.0`. `gitlab.com/my/project`, the developer must create the Git tag `v1.0.0`.
For major versions other than 0 and 1, the module name must be suffixed with For major versions other than 0 and 1, the module name must be suffixed with
`/vX` where X is the major version. For example, version `v2.0.0` of `/vX` where X is the major version. For example, version `v2.0.0` of
...@@ -38,6 +38,10 @@ end with a timestamp and the first 12 characters of the commit identifier: ...@@ -38,6 +38,10 @@ end with a timestamp and the first 12 characters of the commit identifier:
If a VCS tag matches one of these patterns, it is ignored. If a VCS tag matches one of these patterns, it is ignored.
For a complete understanding of Go modules and versioning, see [this series of
blog posts](https://blog.golang.org/using-go-modules) on the official Go
website.
## 'Module' vs 'Package' ## 'Module' vs 'Package'
- A package is a folder containing `*.go` files. - A package is a folder containing `*.go` files.
......
...@@ -54,7 +54,40 @@ NOTE: **Note:** ...@@ -54,7 +54,40 @@ NOTE: **Note:**
GitLab does not currently display Go modules in the **Packages Registry** of a project. 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. Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213770) for details.
### Fetch modules from private projects ## 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](#set-environment-variables). For
details on configuring `GOPROXY`, see [Dependency Management in Go >
Proxies](../../../development/go_guide/dependencies.md#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:
```shell
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:
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`,
`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 `go` does not support transmitting credentials over insecure connections. The
steps below work only if GitLab is configured for HTTPS. steps below work only if GitLab is configured for HTTPS.
...@@ -64,7 +97,7 @@ steps below work only if GitLab is configured for HTTPS. ...@@ -64,7 +97,7 @@ steps below work only if GitLab is configured for HTTPS.
1. Configure Go to skip downloading of checksums for private GitLab projects 1. Configure Go to skip downloading of checksums for private GitLab projects
from the public checksum database. from the public checksum database.
#### Enable Request Authentication ### Enable request authentication
Create a [personal access token](../../profile/personal_access_tokens.md) with Create a [personal access token](../../profile/personal_access_tokens.md) with
the `api` or `read_api` scope and add it to the `api` or `read_api` scope and add it to
...@@ -78,90 +111,53 @@ machine <url> login <username> password <token> ...@@ -78,90 +111,53 @@ machine <url> login <username> password <token>
`<username>` and `<token>` should be your username and the personal access `<username>` and `<token>` should be your username and the personal access
token, respectively. token, respectively.
#### Disable checksum database queries ### Disable checksum database queries
Go can be configured to query a checksum database for module checksums. Go 1.13 When downloading dependencies, by default Go 1.13 and later validate fetched
and later query `sum.golang.org` by default. This fails for modules that are not sources against the checksum database `sum.golang.org`. If the checksum of the
public and thus not accessible to `sum.golang.org`. To resolve this issue, set fetched sources does not match the checksum from the database, Go will not build
`GONOSUMDB` to a comma-separated list of projects or namespaces for which Go the dependency. This causes private modules to fail to build, as
should not query the checksum database. For example, `go env -w `sum.golang.org` cannot fetch the source of private modules and thus cannot
GONOSUMDB=gitlab.com/my/project` persistently configures Go to skip checksum provide a checksum. To resolve this issue, `GONOSUMDB` should be set to a
queries for the project `gitlab.com/my/project`. 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).
Checksum database queries can be disabled for arbitrary prefixes or disabled For example, to disable checksum queries for `gitlab.com/my/project`, set `GONOSUMDB`:
entirely. However, checksum database queries are a security mechanism and as
such they should be disabled selectively and only when necessary. `GOSUMDB=off`
or `GONOSUMDB=*` disables checksum queries entirely. `GONOSUMDB=gitlab.com`
disables checksum queries for all projects hosted on GitLab.com.
## Add GitLab as a Go proxy ```shell
go env -w GONOSUMDB='gitlab.com/my/project,<previous value>'
```
NOTE: **Note:** ## Working with Go
To use a Go proxy, you must be using Go 1.13 or later.
The available proxy endpoints are: If you are unfamiliar with managing dependencies in Go, or Go in general,
consider reviewing the following documentation:
- Project - can fetch modules defined by a project - `/api/v4/projects/:id/packages/go` - [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/)
Go's use of proxies is configured with the `GOPROXY` environment variable, as a ### Set environment variables
comma separated list of URLs. Go 1.14 adds support for comma separated list of
URLs. Go 1.14 adds support for using `go env -w` to manage Go's environment
variables. For example, `go env -w GOPROXY=...` writes to `$GOPATH/env`
(which defaults to `~/.go/env`). `GOPROXY` can also be configured as a normal
environment variable, with RC files or `export GOPROXY=...`.
The default value of `$GOPROXY` is `https://proxy.golang.org,direct`, which
tells `go` to first query `proxy.golang.org` and fallback to direct VCS
operations (`git clone`, `svc checkout`, etc). Replacing
`https://proxy.golang.org` with a GitLab endpoint will direct all fetches
through GitLab. Currently GitLab's Go proxy does not support dependency
proxying, so all external dependencies will be handled directly. If GitLab's
endpoint is inserted before `https://proxy.golang.org`, then all fetches will
first go through GitLab. This can help avoid making requests for private
packages to the public proxy, but `GOPRIVATE` is a much safer way of achieving
that.
For example, with the following configuration, Go will attempt to fetch modules
from 1) GitLab project 1234's Go module proxy, 2) `proxy.golang.org`, and
finally 3) directly with Git (or another VCS, depending on where the module
source is hosted).
```shell Go uses environment variables to control various features. These can be managed
go env -w GOPROXY=https://gitlab.com/api/v4/projects/1234/packages/go,https://proxy.golang.org,direct 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
## 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
Go modules and module versions are handled entirely with Git (or SVN, Mercurial, files. Module versions are defined by VCS tags. To publish a module, push
and so on). A module is a repository containing Go source and a `go.mod` file. A `go.mod` and source files to a VCS repository. To publish a module version, push
version of a module is a Git tag (or equivalent) that is a valid [semantic a VCS tag. See [Dependency Management in Go >
version](https://semver.org), prefixed with 'v'. For example, `v1.0.0` and Versioning](../../../development/go_guide/dependencies.md#versioning) for more
`v1.3.2-alpha` are valid module versions, but `v1` or `v1.2` are not. details on what constitutes a valid module or module version.
Go requires that major versions after v1 involve a change in the import path of
the module. For example, version 2 of the module `gitlab.com/my/project` must be
imported and released as `gitlab.com/my/project/v2`.
For a complete understanding of Go modules and versioning, see [this series of
blog posts](https://blog.golang.org/using-go-modules) on the official Go
website.
## Valid modules and versions
The GitLab Go proxy will ignore modules and module versions that have an invalid
`module` directive in their `go.mod`. Go requires that a package imported as
`gitlab.com/my/project` can be accessed with that same URL, and that the first
line of `go.mod` is `module gitlab.com/my/project`. If `go.mod` names a
different module, compilation will fail. Additionally, Go requires, for major
versions after 1, that the name of the module have an appropriate suffix, for
example `gitlab.com/my/project/v2`. If the `module` directive does not also have
this suffix, compilation will fail.
Go supports 'pseudo-versions' that encode the timestamp and SHA of a commit.
Tags that match the pseudo-version pattern are ignored, as otherwise they could
interfere with fetching specific commits using a pseudo-version. Pseudo-versions
follow one of three formats:
- `vX.0.0-yyyymmddhhmmss-abcdefabcdef`, when no earlier tagged commit exists for X.
- `vX.Y.Z-pre.0.yyyymmddhhmmss-abcdefabcdef`, when most recent prior tag is vX.Y.Z-pre.
- `vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdefabcdef`, when most recent prior tag is vX.Y.Z.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment