Merge branch '205299-go-modules-docs' into 'master'

Update "Use your project as a Go package"

Closes #205299

See merge request gitlab-org/gitlab!34800

doc/user/project/index.md

@@ -261,14 +261,52 @@ When [renaming a user](../profile/index.md#changing-your-username),
 
 ## Use your project as a Go package
 
-Any project can be used as a Go package including private projects in subgroups.
-GitLab responds correctly to `go get` and `godoc.org` discovery requests,
-including the [`go-import`](https://golang.org/cmd/go/#hdr-Remote_import_paths)
-and [`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) meta
-tags, respectively. To use packages hosted in private projects with the `go get`
-command, use a [`.netrc` file](https://ec.haxx.se/usingcurl-netrc.html) and a
-[personal access token](../profile/personal_access_tokens.md) in the password
-field.
+Any project can be used as a Go package. GitLab responds correctly to `go get`
+and `godoc.org` discovery requests, including the
+[`go-import`](https://golang.org/cmd/go/#hdr-Remote_import_paths) and
+[`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) meta tags.
+
+Private projects, including projects in subgroups, can be used as a Go package,
+but may require configuration to work correctly. GitLab will respond correctly
+to `go get` discovery requests for projects that *are not* in subgroups,
+regardless of authentication or authorization.
+[Authentication](#authenticate-go-requests) is required to use a private project
+in a subgroup as a Go package. Otherwise, GitLab will truncate the path for
+private projects in subgroups to the first two segments, causing `go get` to
+fail.
+
+GitLab implements its own Go proxy. This feature must be enabled by an
+administrator and requires additional configuration. See [GitLab Go
+Proxy](../packages/go_proxy/index.md).
+
+### Disable Go module features for private projects
+
+In Go 1.12 and later, Go queries module proxies and checksum databases in the
+process of [fetching a
+module](../../development/go_guide/dependencies.md#fetching). This can be
+selectively disabled with `GOPRIVATE` (disable both),
+[`GONOPROXY`](../../development/go_guide/dependencies.md#proxies) (disable proxy
+queries), and [`GONOSUMDB`](../../development/go_guide/dependencies.md#fetching)
+(disable checksum queries).
+
+`GOPRIVATE`, `GONOPROXY`, and `GONOSUMDB` are comma-separated lists of Go
+modules and Go module prefixes. For example,
+`GOPRIVATE=gitlab.example.com/my/private/project` will disable queries for that
+one project, but `GOPRIVATE=gitlab.example.com` will disable queries for *all*
+projects on GitLab.com. Go will not query module proxies if the module name or a
+prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go will not query checksum
+databases if the module name or a prefix of it appears in `GONOPRIVATE` or
+`GONOSUMDB`.
+
+### Authenticate Go requests
+
+To authenticate requests to private projects made by Go, use a [`.netrc`
+file](https://ec.haxx.se/usingcurl-netrc.html) and a [personal access
+token](../profile/personal_access_tokens.md) in the password field. **This only
+works if your GitLab instance can be accessed with HTTPS.** The `go` command
+will not transmit credentials over insecure connections. This will authenticate
+all HTTPS requests made directly by Go but will not authenticate requests made
+through Git.
 
 For example:
 
@@ -278,6 +316,24 @@ login <gitlab_user_name>
 password <personal_access_token>
 ```
 
+NOTE: **Note:**
+On Windows, Go reads `~/_netrc` instead of `~/.netrc`.
+
+### Authenticate Git fetches
+
+If a module cannot be fetched from a proxy, Go will fall back to using Git (for
+GitLab projects). Git will use `.netrc` to authenticate requests. Alternatively,
+Git can be configured to embed specific credentials in the request URL, or to
+use SSH instead of HTTPS (as Go always uses HTTPS to fetch Git repositories):
+
+```shell
+# embed credentials in any request to GitLab.com:
+git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com"
+
+# use SSH instead of HTTPS:
+git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com"
+```
+
 ## Access project page with project ID
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8.