패키지용 의존성 프록시

요약

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

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>의 이름이 들어갑니다.

기본적으로 Super POM을 통해 Maven Central을 먼저 확인합니다. 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.
선택 사항. 필요한 자격 증명.

이 매개변수를 설정하려면 다음과 같이 진행합니다:

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Settings > Packages and registries를 선택합니다.
Package registry를 확장합니다.
Dependency Proxy에서 사용하는 패키지 형식에 맞게 양식을 작성합니다:

모든 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 패키지의 group ID와 artifact ID를 슬래시로 연결한 값입니다.
<version>은 패키지 버전입니다.
file_name은 파일의 정확한 이름입니다.

예를 들어 다음과 같은 패키지가 있다고 가정합니다:

group ID: com.my_company.
artifact ID: my_package.
version: 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"

패키지용 의존성 프록시

GitLab v19.5

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

원문 보기

번역일: 2026-09-18

요약

Warning

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

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>의 이름이 들어갑니다.

기본적으로 Super POM을 통해 Maven Central을 먼저 확인합니다. 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.
선택 사항. 필요한 자격 증명.

이 매개변수를 설정하려면 다음과 같이 진행합니다:

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Settings > Packages and registries를 선택합니다.
Package registry를 확장합니다.
Dependency Proxy에서 사용하는 패키지 형식에 맞게 양식을 작성합니다:

원격 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 패키지의 group ID와 artifact ID를 슬래시로 연결한 값입니다.
<version>은 패키지 버전입니다.
file_name은 파일의 정확한 이름입니다.

예를 들어 다음과 같은 패키지가 있다고 가정합니다:

group ID: com.my_company.
artifact ID: my_package.
version: 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"