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

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
  • GitLab 17.3에서 변경된 사항: 권한이 없는 go get 요청에 대해 404 오류 반환.

필수 요건:

  • GitLab Go Proxy를 활성화하려면 관리자에게 문의하세요.
  • 서브그룹의 비공식 프로젝트를 Go 패키지로 사용하려면 비공식 프로젝트에 대한 Go 요청 인증이 필요합니다. 인증되지 않은 Go 요청은
    go get이 실패합니다. 서브그룹에 없는 프로젝트는 Go 요청을 인증할 필요가 없습니다.

프로젝트를 Go 패키지로 사용하려면 go get 및 godoc.org 검색 요청을 사용하세요. 다음 메타 태그를 사용할 수 있습니다:

참고:
유효하지 않은 HTTP 자격증명으로 go get 요청을 하면 404 오류를 받습니다.
HTTP 자격증명은 ~/.netrc (MacOS 및 Linux) 또는 ~/_netrc (Windows)에 있습니다.

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

필수 요건:

  • 귀하의 GitLab 인스턴스는 HTTPS로 접근 가능해야 합니다.
  • read_api 범위의 개인 액세스 토큰이 있어야 합니다.

Go 요청을 인증하려면 다음 정보를 포함한 .netrc 파일을 만드세요:

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

Windows에서는 Go가 ~/_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

가져오기를 비활성화하려면:

  1. GOPRIVATE 비활성화:
    • 하나의 프로젝트에 대한 쿼리를 비활성화하려면 GOPRIVATE=gitlab.example.com/my/private/project를 비활성화합니다.
    • GitLab.com의 모든 프로젝트에 대한 쿼리를 비활성화하려면 GOPRIVATE=gitlab.example.com을 비활성화합니다.
  2. GONOPROXY에서 프록시 쿼리를 비활성화합니다.
  3. GONOSUMDB에서 체크섬 쿼리를 비활성화합니다.
  • 모듈 이름 또는 그 접두사가 GOPRIVATE 또는 GONOPROXY에 있으면 Go는 모듈 프록시를 쿼리하지 않습니다.
  • 모듈 이름 또는 그 접두사가 GONOPRIVATE 또는 GONOSUMDB에 있으면 Go는 체크섬 데이터베이스를 쿼리하지 않습니다.

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

Go 모듈이 gitlab.com/namespace/subgroup/go-module와 같은 개인 하위 그룹에 위치한 경우 Git 인증이 작동하지 않습니다.

이는 go get이 리포지토리 경로를 찾기 위해 인증되지 않은 요청을 하기 때문에 발생합니다.

.netrc 파일을 통한 HTTP 인증 없이 GitLab은 인증되지 않은 사용자가 프로젝트의 존재를 노출하는 보안 위험을 방지하기 위해 gitlab.com/namespace/subgroup.git로 응답합니다.

결과적으로 Go 모듈을 다운로드할 수 없습니다.

안타깝게도 Go는 .netrc 외에 요청 인증 수단을 제공하지 않습니다. 향후 버전에서는 Go가 임의의 인증 헤더에 대한 지원을 추가할 수 있습니다.

자세한 내용은 golang/go#26232를 참조하세요.

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

go get 요청을 건너뛰고 Go가 Git 인증을 직접 사용하도록 강제하는 방법이 있지만 모듈 이름의 수정이 필요합니다.

모듈 경로 뒤쪽에 VCS 수식어(.bzr, .fossil, .git, .hg, .svn 중 하나)가 있는 경우, go 명령은 해당 경로 수식어까지의 모든 것을 리포지토리 URL로 사용합니다. 예를 들어, 모듈 경로가 example.com/foo.git/bar인 경우 go 명령은 git을 사용하여 example.com/foo.git에서 리포지토리를 다운로드하며, bar 하위 디렉토리에서 모듈을 찾을 것으로 예상합니다.

Go 문서에서 발췌

  1. 개인 하위 그룹의 Go 모듈 go.mod로 이동합니다.

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

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

  4. 이 모듈에 의존하는 Go 프로젝트를 방문하고 import 호출을 조정합니다.
    예를 들어, import gitlab.com/namespace/subgroup/go-module.git로 변경합니다.

이 변경 후에 Go 모듈을 올바르게 가져올 수 있어야 합니다.
예를 들어, GOPRIVATE=gitlab.com/namespace/* go mod tidy를 실행합니다.

Geo 2차 사이트에서 Go 모듈 가져오기

2차 Geo 서버에서 Go 모듈이 포함된 Git 리포지토리에 접근하려면 Geo를 사용하세요.

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

SSH를 사용하여 Geo 2차 서버에 접근하기

SSH를 사용하여 Geo 2차 서버에 접근하려면:

  1. 클라이언트에서 Git을 재구성하여 기본 서버를 2차 서버로 트래픽을 전송하도록 설정합니다:

    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에는 2차 사이트 도메인 이름을 사용합니다.

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

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

Geo 보조 서버에 HTTP로 액세스하기

보조 서버에 복제되는 지속적인 액세스 토큰을 사용해야 합니다. HTTP로 Go 모듈을 가져오기 위해 CI/CD 작업 토큰을 사용할 수 없습니다.

HTTP로 Geo 보조 서버에 액세스하려면:

  1. 클라이언트에서 Git insteadOf 리디렉션을 추가합니다:

    git config --global url."https://gitlab-secondary.example.com".insteadOf "https://gitlab.example.com"
    • gitlab.example.com의 경우, 기본 사이트 도메인 이름을 사용합니다.
    • gitlab-secondary.example.com의 경우, 보조 사이트 도메인 이름을 사용합니다.

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

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

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