---

프로젝트를 Go 패키지로 사용하기#

  - 
  Tier: Free, Premium, Ultimate

- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

History

• GitLab 17.3에서 변경됨: 인증되지 않은 go get 요청에 대해 404 오류를 반환하도록 변경되었습니다.

사전 요구사항:

• 하위 그룹의 비공개 프로젝트를 Go 패키지로 사용하려면 Go 요청을 인증해야 합니다. 인증되지 않은 Go 요청은 go get 실패를 유발합니다. 하위 그룹에 속하지 않은 프로젝트의 경우 Go 요청을 인증할 필요가 없습니다.

프로젝트를 Go 패키지로 사용하려면 go get 및 godoc.org 디스커버리 요청을 사용합니다. 다음 메타 태그를 사용할 수 있습니다:

• go-import

• go-source

  잘못된 HTTP 자격 증명으로 go get 요청을 보내면 404 오류가 반환됩니다. HTTP 자격 증명은 ~/.netrc(MacOS 및 Linux) 또는 ~/_netrc(Windows)에서 확인할 수 있습니다. Go 1.24 이상에서는 GOAUTH 환경 변수를 사용하여 자격 증명을 제공할 수도 있습니다. 자세한 내용은 GOAUTH로 인증하기를 참조하세요.

비공개 프로젝트에 대한 Go 요청 인증#

사전 요구사항:

• GitLab 인스턴스가 HTTPS로 접근 가능해야 합니다.

• read_api 범위를 가진 개인 액세스 토큰이 있어야 합니다.

GOAUTH로 인증하기#

Go 1.24 이상에서는 GOAUTH 환경 변수를 사용하여 커스텀 명령어로 자격 증명을 제공합니다.

`GOAUTH`의 `git dir` 값은 깊이가 1을 초과하는 중첩된 하위 그룹의 비공개 프로젝트에서는 작동하지 않습니다. 대신 커스텀 명령어를 사용하세요.

GOAUTH로 인증하려면 Go 요청에 HTTP Basic 인증 헤더를 추가하는 커스텀 명령어를 만드세요. 다음 예시는 git credential fill이 반환하는 Git over HTTPS 자격 증명을 사용하여 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"

이 스크립트를 사용하려면:

스크립트를 파일로 저장합니다. 예: gitlab_goauth.sh.

파일을 실행 가능하게 만듭니다:

chmod +x gitlab_goauth.sh

GOAUTH 환경 변수를 명령어의 절대 경로로 설정합니다:

export GOAUTH="<absolute_path_to_your_command>"

또는 기존 .netrc 파일을 GOAUTH와 함께 사용하려면:

export GOAUTH="netrc"

.netrc로 인증하기#

.netrc 파일로 Go 요청을 인증하려면 다음 정보로 파일을 생성합니다:

machine gitlab.example.com
login <gitlab_user_name>
password <personal_access_token>

Windows에서는 Go가 ~/.netrc 대신 ~/_netrc를 읽습니다.

go 명령어는 보안되지 않은 연결을 통해 자격 증명을 전송하지 않습니다. Go가 수행하는 HTTPS 요청은 인증하지만, Git을 통한 요청은 인증하지 않습니다.

Git 요청 인증#

Go가 프록시에서 모듈을 가져올 수 없는 경우 Git을 사용합니다. Git은 .netrc 파일을 사용하여 요청을 인증하지만, 다른 인증 방법을 구성할 수도 있습니다.

Git을 다음 중 하나로 구성합니다:

요청 URL에 자격 증명 포함:

git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com"

HTTPS 대신 SSH 사용:

git config --global url."git@gitlab.example.com:".insteadOf "https://gitlab.example.com/"

비공개 프로젝트에 대한 Go 모듈 페칭 비활성화#

모듈 또는 패키지를 가져오기 위해 Go는 다음 환경 변수를 사용합니다:

• GOPRIVATE

• GONOPROXY

• GONOSUMDB

페칭을 비활성화하려면:

• GOPRIVATE 비활성화:

특정 프로젝트에 대한 쿼리를 비활성화하려면 GOPRIVATE=gitlab.example.com/my/private/project를 비활성화합니다.

• GitLab.com의 모든 프로젝트에 대한 쿼리를 비활성화하려면 GOPRIVATE=gitlab.example.com을 비활성화합니다.

• GONOPROXY에서 프록시 쿼리를 비활성화합니다.

• GONOSUMDB에서 체크섬 쿼리를 비활성화합니다.

• 모듈 이름 또는 그 접두사가 GOPRIVATE 또는 GONOPROXY에 있으면 Go는 모듈 프록시를 쿼리하지 않습니다.

• 모듈 이름 또는 그 접두사가 GOPRIVATE 또는 GONOSUMDB에 있으면 Go는 체크섬 데이터베이스를 쿼리하지 않습니다.

비공개 하위 그룹에 대한 Git 요청 인증#

Go 모듈이 gitlab.com/namespace/subgroup/go-module과 같은 비공개 하위 그룹 아래에 있는 경우 Git 인증이 작동하지 않습니다. 이는 go get이 리포지터리 경로를 검색하기 위해 인증되지 않은 요청을 보내기 때문입니다. 인증 없이는 GitLab이 인증되지 않은 사용자에게 프로젝트의 존재를 노출하는 보안 위험을 방지하기 위해 gitlab.com/namespace/subgroup.git으로 응답합니다. 그 결과 Go 모듈을 다운로드할 수 없게 됩니다.

비공개 하위 그룹의 Go 모듈을 다운로드하려면 Go 인증을 구성할 수 있습니다.

해결 방법: 모듈 이름에 .git 사용#

go get 요청을 건너뛰고 Go가 직접 Git 인증을 사용하도록 강제하는 방법이 있지만, 이를 위해서는 모듈 이름을 수정해야 합니다. Go 문서에서 발췌:

모듈 경로에 경로 구성 요소 끝에 VCS 한정자(.bzr, .fossil, .git, .hg, .svn 중 하나)가 있으면 go 명령어는 해당 경로 한정자까지의 모든 내용을 리포지터리 URL로 사용합니다. 예를 들어 모듈 example.com/foo.git/bar의 경우, go 명령어는 Git을 사용하여 example.com/foo.git의 리포지터리를 다운로드하고 bar 하위 디렉터리에서 모듈을 찾으려고 합니다.

• 비공개 하위 그룹의 Go 모듈에 있는 go.mod로 이동합니다.

• 모듈 이름에 .git을 추가합니다. 예를 들어, module gitlab.com/namespace/subgroup/go-module을 module gitlab.com/namespace/subgroup/go-module.git으로 이름을 변경합니다.

• 이 변경 사항을 커밋하고 푸시합니다.

• 이 모듈에 의존하는 Go 프로젝트를 방문하여 import 호출을 조정합니다. 예: import gitlab.com/namespace/subgroup/go-module.git.

이 변경 후 Go 모듈이 올바르게 페칭되어야 합니다. 예: GOPRIVATE=gitlab.com/namespace/* go mod tidy.

Geo 보조 사이트에서 Go 모듈 페칭#

Geo를 사용하여 보조 Geo 서버의 Go 모듈이 포함된 Git 리포지터리에 접근합니다.

SSH 또는 HTTP를 사용하여 Geo 보조 서버에 접근할 수 있습니다.

SSH를 사용하여 Geo 보조 서버 접근#

SSH로 Geo 보조 서버에 접근하려면:

클라이언트에서 Git을 재구성하여 기본 서버의 트래픽을 보조 서버로 전송합니다:

git config --global url."git@gitlab-secondary.example.com".insteadOf "https://gitlab.example.com"
git config --global url."git@gitlab-secondary.example.com".insteadOf "http://gitlab.example.com"

gitlab.example.com에는 기본 사이트 도메인 이름을 사용합니다.

• gitlab-secondary.example.com에는 보조 사이트 도메인 이름을 사용합니다.

클라이언트가 GitLab 리포지터리에 SSH로 접근할 수 있도록 설정되어 있는지 확인합니다. 기본 서버에서 테스트할 수 있으며, GitLab이 공개 키를 보조 서버로 복제합니다.

go get 요청은 기본 Geo 서버에 대한 HTTP 트래픽을 생성합니다. 모듈 다운로드가 시작되면 insteadOf 구성이 트래픽을 보조 Geo 서버로 전송합니다.

HTTP를 사용하여 Geo 보조 서버 접근#

보조 서버에 복제되는 영구 액세스 토큰을 사용해야 합니다. HTTP로 Go 모듈을 가져오는 데 CI/CD job 토큰을 사용할 수 없습니다.

HTTP로 Geo 보조 서버에 접근하려면:

클라이언트에 Git insteadOf 리다이렉트를 추가합니다:

git config --global url."https://gitlab-secondary.example.com".insteadOf "https://gitlab.example.com"

gitlab.example.com에는 기본 사이트 도메인 이름을 사용합니다.

• gitlab-secondary.example.com에는 보조 사이트 도메인 이름을 사용합니다.

개인 액세스 토큰을 생성하고 클라이언트의 ~/.netrc 파일에 자격 증명을 추가합니다:

machine gitlab.example.com login USERNAME password TOKEN
machine gitlab-secondary.example.com login USERNAME password TOKEN

go get 요청은 기본 Geo 서버에 대한 HTTP 트래픽을 생성합니다. 모듈 다운로드가 시작되면 insteadOf 구성이 트래픽을 보조 Geo 서버로 전송합니다.