패키지용 의존성 프록시

요약

의존성 프록시는 베타입니다. GitLab 의존성 프록시는 패키지를 다운로드하고 복사본을 저장하는 로컬 프록시 서버입니다. 패키지를 처음 요청할 때 GitLab은 업스트림 패키지 레지스트리에서 가져와 프로젝트에 복사본을 저장합니다.

히스토리

GitLab 16.6에서 packages_dependency_proxy_maven이라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화됩니다.
GitLab 16.8에서 GitLab.com 및 GitLab Self-Managed에서 활성화되었습니다. 기능 플래그 packages_dependency_proxy_maven이 제거되었습니다.

Warning

의존성 프록시는 베타입니다. 이 기능을 사용하기 전에 문서를 주의 깊게 검토하세요.

GitLab 의존성 프록시는 패키지를 다운로드하고 복사본을 저장하는 로컬 프록시 서버입니다.

패키지를 처음 요청할 때 GitLab은 업스트림 패키지 레지스트리에서 가져와 프로젝트에 복사본을 저장합니다. 동일한 패키지를 다시 요청하면 GitLab은 프로젝트의 패키지 레지스트리에 저장된 복사본을 제공합니다.

이 접근 방식은 외부 소스에서의 다운로드 수를 줄이고 패키지 빌드를 더 빠르게 합니다.

의존성 프록시 활성화#

패키지용 의존성 프록시를 사용하려면 프로젝트가 올바르게 구성되어 있고, 캐시에서 가져오는 사용자에게 필요한 인증이 있는지 확인합니다:

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

고급 캐싱#

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

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

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

요청된 파일이 프로젝트의 패키지 레지스트리에서 발견되면 반환됩니다.
파일을 찾지 못하면 업스트림 패키지 레지스트리에서 가져옵니다.

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

Maven 패키지의 경우:

패키지 레지스트리	고급 캐싱 지원?
GitLab	✅
Maven Central	✅
Artifactory	✅
Sonatype Nexus	✅
GitHub Packages	❌

권한#

의존성 프록시가 파일을 가져올 때 다음이 발생합니다:

의존성 프록시는 프로젝트의 패키지 레지스트리에서 파일을 검색합니다. 이것은 읽기 작업입니다.
의존성 프록시가 프로젝트의 패키지 레지스트리에 패키지 파일을 게시할 수 있습니다. 이것은 쓰기 작업입니다.

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

프로젝트 가시성	최소 역할	패키지 파일 읽기 가능?	패키지 파일 쓰기 가능?	동작
공개	익명	❌	❌	요청 거부.
공개	Guest	✅	❌	캐시 또는 원격 레지스트리에서 패키지 파일 반환.
공개	Developer	✅	✅	캐시 또는 원격 레지스트리에서 패키지 파일 반환. 파일이 캐시에 게시됩니다.
내부	익명	❌	❌	요청 거부
내부	Guest	✅	❌	캐시 또는 원격 레지스트리에서 패키지 파일 반환.
내부	Developer	✅	✅	캐시 또는 원격 레지스트리에서 패키지 파일 반환. 파일이 캐시에 게시됩니다.
비공개	익명	❌	❌	요청 거부
비공개	Reporter	✅	❌	캐시 또는 원격 레지스트리에서 패키지 파일 반환.
비공개	Developer	✅	✅	캐시 또는 원격 레지스트리에서 패키지 파일 반환. 파일이 캐시에 게시됩니다.

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

시간이 지남에 따라 캐시가 올바르게 채워지도록 하려면 Developer, Maintainer 또는 Owner 역할을 가진 사용자가 의존성 프록시를 사용하여 패키지를 가져오도록 해야 합니다.

클라이언트 구성#

의존성 프록시용 클라이언트 구성은 패키지 레지스트리용 클라이언트 구성과 유사합니다.

Maven 패키지의 경우#

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

mvn
gradle
sbt

인증의 경우 Maven 패키지 레지스트리에서 허용하는 모든 방법을 사용할 수 있습니다. 복잡성이 낮기 때문에 기본 HTTP 인증 방법을 사용하는 것이 좋습니다.

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

기본 HTTP 인증의 지침을 따릅니다.

엔드포인트 URL https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven을 사용해야 합니다.
클라이언트 구성을 완료합니다:

기본 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은 Super POM을 통해 먼저 확인됩니다. 그러나 mvn이 먼저 GitLab 엔드포인트를 확인하도록 강제할 수 있습니다. 이를 위해 요청 전달의 지침을 따르세요.

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 인증 섹션에서 설명됩니다.

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.
선택 사항. 필요한 자격 증명.

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

상단 표시줄에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 설정 > 패키지 및 레지스트리를 선택합니다.
패키지 레지스트리를 확장합니다.
의존성 프록시 아래에서 패키지 형식에 대한 양식을 작성합니다:

모든 Maven 패키지 레지스트리를 의존성 프록시에 연결할 수 있습니다. Maven 패키지 레지스트리 사용자 이름과 비밀번호로 연결을 인증할 수 있습니다.

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

URL - 원격 레지스트리의 URL.
Username - 선택 사항. 원격 레지스트리와 함께 사용할 사용자 이름.
Password - 선택 사항. 원격 레지스트리와 함께 사용할 비밀번호.

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

문제 해결#

수동 파일 가져오기 오류#

cURL로 파일을 수동으로 가져올 수 있습니다. 그러나 다음 응답 중 하나가 발생할 수 있습니다:

404 Not Found - 의존성 프록시 설정 객체가 존재하지 않거나 요구 사항이 충족되지 않아 찾을 수 없습니다.
401 Unauthorized - 사용자가 올바르게 인증되었지만 의존성 프록시 객체에 액세스하는 데 필요한 권한이 없습니다.
403 Forbidden - GitLab 라이선스 수준에 문제가 있습니다.
502 Bad Gateway - 원격 패키지 레지스트리가 파일 요청을 처리할 수 없습니다. 의존성 프록시 설정을 확인하세요.
504 Gateway Timeout - 원격 패키지 레지스트리가 시간 초과되었습니다. 의존성 프록시 설정을 확인하세요.

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"

패키지용 의존성 프록시

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

원문 보기

번역일: 2026-05-22

요약

히스토리

GitLab 16.6에서 packages_dependency_proxy_maven이라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화됩니다.
GitLab 16.8에서 GitLab.com 및 GitLab Self-Managed에서 활성화되었습니다. 기능 플래그 packages_dependency_proxy_maven이 제거되었습니다.

Warning

의존성 프록시는 베타입니다. 이 기능을 사용하기 전에 문서를 주의 깊게 검토하세요.

GitLab 의존성 프록시는 패키지를 다운로드하고 복사본을 저장하는 로컬 프록시 서버입니다.

이 접근 방식은 외부 소스에서의 다운로드 수를 줄이고 패키지 빌드를 더 빠르게 합니다.

의존성 프록시 활성화#

패키지용 의존성 프록시를 사용하려면 프로젝트가 올바르게 구성되어 있고, 캐시에서 가져오는 사용자에게 필요한 인증이 있는지 확인합니다:

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

고급 캐싱#

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

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

요청된 파일이 프로젝트의 패키지 레지스트리에서 발견되면 반환됩니다.
파일을 찾지 못하면 업스트림 패키지 레지스트리에서 가져옵니다.

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

Maven 패키지의 경우:

패키지 레지스트리	고급 캐싱 지원?
GitLab	✅
Maven Central	✅
Artifactory	✅
Sonatype Nexus	✅
GitHub Packages	❌

권한#

의존성 프록시가 파일을 가져올 때 다음이 발생합니다:

의존성 프록시는 프로젝트의 패키지 레지스트리에서 파일을 검색합니다. 이것은 읽기 작업입니다.
의존성 프록시가 프로젝트의 패키지 레지스트리에 패키지 파일을 게시할 수 있습니다. 이것은 쓰기 작업입니다.

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

프로젝트 가시성	최소 역할	패키지 파일 읽기 가능?	패키지 파일 쓰기 가능?	동작
공개	익명	❌	❌	요청 거부.
공개	Guest	✅	❌	캐시 또는 원격 레지스트리에서 패키지 파일 반환.
공개	Developer	✅	✅	캐시 또는 원격 레지스트리에서 패키지 파일 반환. 파일이 캐시에 게시됩니다.
내부	익명	❌	❌	요청 거부
내부	Guest	✅	❌	캐시 또는 원격 레지스트리에서 패키지 파일 반환.
내부	Developer	✅	✅	캐시 또는 원격 레지스트리에서 패키지 파일 반환. 파일이 캐시에 게시됩니다.
비공개	익명	❌	❌	요청 거부
비공개	Reporter	✅	❌	캐시 또는 원격 레지스트리에서 패키지 파일 반환.
비공개	Developer	✅	✅	캐시 또는 원격 레지스트리에서 패키지 파일 반환. 파일이 캐시에 게시됩니다.

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

클라이언트 구성#

의존성 프록시용 클라이언트 구성은 패키지 레지스트리용 클라이언트 구성과 유사합니다.

Maven 패키지의 경우#

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

mvn
gradle
sbt

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

기본 HTTP 인증의 지침을 따릅니다.

엔드포인트 URL https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven을 사용해야 합니다.
클라이언트 구성을 완료합니다:

기본 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> 이름을 포함합니다.

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 인증 섹션에서 설명됩니다.

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.
선택 사항. 필요한 자격 증명.

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

상단 표시줄에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 설정 > 패키지 및 레지스트리를 선택합니다.
패키지 레지스트리를 확장합니다.
의존성 프록시 아래에서 패키지 형식에 대한 양식을 작성합니다:

모든 Maven 패키지 레지스트리를 의존성 프록시에 연결할 수 있습니다. Maven 패키지 레지스트리 사용자 이름과 비밀번호로 연결을 인증할 수 있습니다.

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

URL - 원격 레지스트리의 URL.
Username - 선택 사항. 원격 레지스트리와 함께 사용할 사용자 이름.
Password - 선택 사항. 원격 레지스트리와 함께 사용할 비밀번호.

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

문제 해결#

수동 파일 가져오기 오류#

cURL로 파일을 수동으로 가져올 수 있습니다. 그러나 다음 응답 중 하나가 발생할 수 있습니다:

404 Not Found - 의존성 프록시 설정 객체가 존재하지 않거나 요구 사항이 충족되지 않아 찾을 수 없습니다.
401 Unauthorized - 사용자가 올바르게 인증되었지만 의존성 프록시 객체에 액세스하는 데 필요한 권한이 없습니다.
403 Forbidden - GitLab 라이선스 수준에 문제가 있습니다.
502 Bad Gateway - 원격 패키지 레지스트리가 파일 요청을 처리할 수 없습니다. 의존성 프록시 설정을 확인하세요.
504 Gateway Timeout - 원격 패키지 레지스트리가 시간 초과되었습니다. 의존성 프록시 설정을 확인하세요.

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"