Use a project as a Go package

Prerequisites:

• To use a private project in a subgroup as a Go package, you must authenticate Go requests. Go requests that are not authenticated cause go get to fail. You don’t need to authenticate Go requests for projects that are not in subgroups.

To use a project as a Go package, use the go get and godoc.org discovery requests. You can use the meta tags:

• go-import
• go-source

Authenticate Go requests to private projects

Prerequisites:

• Your GitLab instance must be accessible with HTTPS.
• You must have one of the following:
  • A personal access token with read_api scope.
  • A fine-grained personal access token with the Download permission for the Code resource, scoped to the project.

Authenticate with GOAUTH

In Go 1.24 and later, use the GOAUTH environment variable to provide credentials with a custom command.

To authenticate with GOAUTH, create a custom command that adds an HTTP Basic authentication header to Go requests. The following example uses your Git over HTTPS credentials, returned by git credential fill, to authenticate requests to gitlab.com:

#!/usr/bin/env bash
GITLAB_URL="https://gitlab.com"

creds=$(echo "url=${GITLAB_URL}" | git credential fill 2>&1) || {
  printf >&2 'error: git credential fill failed:\n%s\n' "$creds"
  exit 1
}

username=""
password=""
while IFS='=' read -r key value; do
  case "$key" in
    username) username="$value" ;;
    password) password="$value" ;;
  esac
done <<< "$creds"

if [ -z "$username" ] || [ -z "$password" ]; then
  printf >&2 'error: git credential fill did not return a username or password for %s\n' "$GITLAB_URL"
  exit 1
fi

encoded=$(printf '%s:%s' "$username" "$password" | base64 | tr -d '\n')

# Expected output format: https://pkg.go.dev/cmd/go@master#hdr-GOAUTH_environment_variable
printf '%s\n\nAuthorization: Basic %s\n\n' "$GITLAB_URL" "$encoded"

To use this script:

1. Save the script to a file, for example gitlab_goauth.sh.

2. Make the file executable:

   shell

   chmod +x gitlab_goauth.sh

3. Set the GOAUTH environment variable to the absolute path of your command:

   shell

   export GOAUTH="<absolute_path_to_your_command>"