패키지를 위한 의존성 프록시

Tier: 프리미엄, 얼티밋 Offering: GitLab.com, 셀프 매니지드, GitLab 전용 Status: 베타
caution
의존성 프록시는 베타 상태입니다. 이 기능을 사용하기 전에 문서를 주의 깊게 검토하세요.

패키지를 위한 GitLab 의존성 프록시는 자주 끌어오는 패키지를 위한 로컬 프록시입니다. 이는 프로젝트 수준에서 작동하는 풀-스루 캐시로 구현되었습니다.

패키지는 상류 패키지 레지스트리에서 끌어와 자동으로 프로젝트 패키지 레지스트리에 발행됩니다. 이후 동일한 요청은 프로젝트 패키지 레지스트리로 충족됩니다. 패키지를 위한 의존성 프록시를 사용하여 상류 레지스트리로의 불필요한 트래픽을 줄일 수 있습니다.

의존성 프록시 활성화

패키지를 위한 의존성 프록시를 사용하려면 프로젝트가 적절하게 구성되어 있고, 캐시에서 끌어오는 사용자가 필요한 인증을 갖고 있는지 확인하세요.

  1. 전역 구성에서 다음 기능이 비활성화되어 있는 경우 활성화하세요:
  2. 프로젝트 설정에서 package 기능이 비활성화되어 있는 경우, 활성화하세요. 기본적으로 활성화됩니다.
  3. 인증 방법을 추가하세요. 의존성 프록시는 패키지 레지스트리와 동일한 인증 방법을 지원합니다:

고급 캐싱

패키지를 위한 의존성 프록시는 가능한 경우 프로젝트 패키지 레지스트리에 패키지를 저장하기 위해 고급 캐싱을 사용합니다.

고급 캐싱은 프로젝트 패키지 레지스트리와 상류 패키지 레지스트리 간의 일관성을 확인합니다. 상류 레지스트리에 업데이트된 파일이 있는 경우 의존성 프록시는 해당 파일을 사용하여 캐시된 파일을 업데이트합니다.

고급 캐싱이 지원되지 않는 경우 의존성 프록시는 다음과 같은 동작으로 돌아갑니다:

  • 요청된 파일이 프로젝트 패키지 레지스트리에 있는 경우 반환됩니다.
  • 파일이 없는 경우 상류 패키지 레지스트리에서 가져옵니다.

고급 캐싱 지원은 상류 패키지 레지스트리가 의존성 프록시 요청에 응답하는 방식과 사용하는 패키지 형식에 따라 다릅니다.

Maven
패키지 레지스트리 고급 캐싱 지원 여부
GitLab 예
Maven Central 예
Artifactory 예
Sonatype Nexus 예
GitHub Packages 아니요

권한

의존성 프록시가 파일을 끌어오면 다음이 발생합니다:

  1. 의존성 프록시는 프로젝트 패키지 레지스트리에서 파일을 찾습니다. 이는 읽기 작업입니다.
  2. 의존성 프록시는 패키지 파일을 프로젝트 패키지 레지스트리에 발행할 수 있습니다. 이는 쓰기 작업입니다.

두 단계가 모두 실행되는지는 사용자 권한에 따라 다릅니다. 의존성 프록시는 패키지 레지스트리와 동일한 권한을 사용합니다.

프로젝트 가시성 최소 역할 패키지 파일 읽기 가능 여부 패키지 파일 쓰기 가능 여부 동작
공개 익명 아니요 아니요 요청이 거부됩니다.
공개 게스트 예 아니요 패키지 파일은 캐시 또는 원격 레지스트리에서 반환됩니다.
공개 개발자 예 예 패키지 파일은 캐시 또는 원격 레지스트리에서 반환됩니다. 파일은 캐시에 발행됩니다.
내부 익명 아니요 아니요 요청이 거부됩니다.
내부 게스트 예 아니요 패키지 파일은 캐시 또는 원격 레지스트리에서 반환됩니다.
내부 개발자 예 예 패키지 파일은 캐시 또는 원격 레지스트리에서 반환됩니다. 파일은 캐시에 발행됩니다.
비공개 익명 아니요 아니요 요청이 거부됩니다.
비공개 기고자 예 아니요 패키지 파일은 캐시 또는 원격 레지스트리에서 반환됩니다.
비공개 개발자 예 예 패키지 파일은 캐시 또는 원격 레지스트리에서 반환됩니다. 파일은 캐시에 발행됩니다.

최소한 의존성 프록시를 사용할 수 있는 사용자는 프로젝트의 패키지 레지스트리도 사용할 수 있어야 합니다.

시간이 지남에 따라 캐시가 적절하게 채워지도록 하려면 적어도 개발자 역할을 가진 사용자가 의존성 프록시를 사용하여 패키지를 끌어오는지 확인해야 합니다.

클라이언트 구성

의존성 프록시의 클라이언트를 구성하는 방법은 패키지 레지스트리를 위한 클라이언트를 구성하는 것과 유사합니다.

Maven 패키지의 경우

Maven 패키지의 경우, 의존성 프록시에서 패키지 레지스트리가 지원하는 모든 클라이언트가 지원됩니다.

  • mvn
  • gradle
  • sbt

인증을 위해 Maven 패키지 레지스트리에서 허용하는 모든 방법을 사용할 수 있습니다. 메소드가 복잡하지 않기 때문에 기본 HTTP 인증 방법을 사용해야 합니다.

클라이언트를 구성하려면:

  1. 기본 HTTP 인증 안내에 따릅니다.

    https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven과 같은 엔드포인트 URL을 사용했는지 확인하세요.

  2. 클라이언트를 구성하세요.

mvn

기본 HTTP 인증이 허용됩니다. 그러나 mvn이 더 적은 네트워크 요청을 사용하도록 사용자 정의 HTTP 헤더 인증을 사용해야 합니다.

pom.xml 파일에 repository 요소를 추가하세요: 

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven</url>
  </repository>
</repositories>

다음과 같습니다:

  • <project_id>는 의존성 프록시로 사용할 프로젝트의 ID입니다.
  • <id>에는 인증 구성에서 사용된 <server>의 이름이 포함되어 있습니다.

기본적으로 Maven Central은 Supoer POM을 통해 먼저 확인됩니다. 그러나 mvn에게 GitLab 엔드포인트를 먼저 확인하도록 하려면 요청 전달 안내에 따릅니다.

gradle

build.gradle 파일에 repositories 섹션을 추가하세요.

  • Groovy DSL에서: 

    repositories {
    maven {
        url "https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven"
        name "GitLab"
        credentials(PasswordCredentials) {
            username = 'REPLACE_WITH_NAME'
            password = gitLabPrivateToken
        }
        authentication {
            basic(BasicAuthentication)
        }
    }
}

  • Kotlin DSL에서: 

    repositories {
    maven {
        url = uri("https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven")
        name = "GitLab"
        credentials(BasicAuthentication::class) {
            username = "REPLACE_WITH_NAME"
            password = findProperty("gitLabPrivateToken") as String?
        }
        authentication {
            create("basic", BasicAuthentication::class)
        }
    }
}

이 예에서:

  • <project_id>는 의존성 프록시로 사용할 프로젝트의 ID입니다.
  • REPLACE_WITH_NAME은 기본 HTTP 인증 섹션에 설명되어 있습니다.
sbt

build.sbt에 다음 라인을 추가하세요: 

resolvers += ("gitlab" at "https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven")

credentials += Credentials("GitLab Packages Registry", "<host>", "<name>", "<token>")

이 예에서:

  • <project_id>는 의존성 프록시로 사용할 프로젝트의 ID입니다.
  • <host>는 프로토콜 스키마나 포트를 제외한 <endpoint url>에 포함된 호스트입니다. 예: gitlab.example.com.
  • <name> 및 <token>은 기본 HTTP 인증 섹션에 설명되어 있습니다.

원격 레지스트리 구성

의존성 프록시는 다음 구성이 필요합니다.

  • 원격 패키지 레지스트리의 URL.
  • 선택 사항. 필요한 자격 증명.

이러한 매개변수를 설정하려면:

  1. 왼쪽 사이드 바에서 검색 또는 이동을 선택하고 프로젝트를 찾으세요.
  2. 설정 > 패키지 및 레지스트리를 선택하세요.
  3. 의존성 프록시 아래에서 패키지 형식에 맞는 양식을 완성하세요:
Maven

어떤 Maven 패키지 레지스트리든 의존성 프록시에 연결할 수 있습니다. Maven 패키지 레지스트리 사용자 이름과 암호로 연결을 승인할 수 있습니다.

원격 Maven 패키지 레지스트리를 설정하거나 업데이트하려면 양식에서 다음 필드를 업데이트하세요.

  • URL - 원격 레지스트리의 URL.
  • Username - 선택 사항. 원격 레지스트리와 사용할 사용자 이름.
  • Password - 선택 사항. 원격 레지스트리와 사용할 암호.

사용자 이름과 암호를 모두 설정하거나 두 필드 모두 비워둬야 합니다.

문제 해결

수동 파일 가져오기 오류

cURL로 수동으로 파일을 가져올 수 있습니다. 그러나 다음 응답 중 하나를 만날 수 있습니다.

  • 404 Not Found - 의존성 프록시 설정 객체가 존재하지 않거나 요구 사항을 충족하지 못했기 때문에 찾을 수 없습니다.
  • 401 Unauthorized - 사용자가 적절하게 인증되었지만 의존성 프록시 객체에 액세스할 적절한 권한이 없습니다.
  • 403 Forbidden - GitLab 라이선스 레벨에 문제가 있습니다.
  • 502 Bad Gateway - 원격 패키지 레지스트리가 파일 요청을 충족시키지 못했습니다. 의존성 프록시 설정을 확인하세요.
  • 504 Gateway Timeout - 원격 패키지 레지스트리의 시간이 초과되었습니다. 의존성 프록시 설정을 확인하세요.
Maven
curl --fail-with-body --verbose "https://<username>:<personal access token>@gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven/<group id and artifact id>/<version>/<file_name>"
  • <username> 및 <personal access token>은 GitLab 인스턴스의 의존성 프록시에 액세스하는 데 사용되는 자격 증명입니다.
  • <project_id>는 프로젝트 ID입니다.
  • <group id and artifact id>는 슬래시로 연결된 Maven 패키지 그룹 ID 및 아티팩트 ID입니다.
  • <version>은 패키지 버전입니다.
  • file_name은 파일의 정확한 이름입니다.

예를 들어 다음과 같은 패키지가 있는 경우:

  • 그룹 ID: com.my_company.
  • 아티팩트 ID: my_package.
  • 버전: 1.2.3.

패키지를 수동으로 가져오기 위한 요청은 다음과 같습니다: 

curl --fail-with-body --verbose "https://<username>:<personal access token>@gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven/com/my_company/my_package/1.2.3/my_package-1.2.3.pom"