히스토리

• GitLab 17.4에서 virtual_registry_maven이라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화됨.
• GitLab 18.1에서 기능 플래그가 maven_virtual_registry로 변경되었습니다. 기본적으로 비활성화됨. 기능 플래그 virtual_registry_maven 제거됨.
• GitLab 18.1에서 실험에서 베타로 변경되었습니다.
• GitLab 18.2에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 활성화되었습니다.

이 API를 사용하여:

• Maven 가상 레지스트리를 생성하고 관리합니다.
• 업스트림 레지스트리를 구성합니다.
• 캐시 항목을 관리합니다.
• 패키지 다운로드 및 업로드를 처리합니다.

Maven 가상 레지스트리 관리#

다음 엔드포인트를 사용하여 Maven 가상 레지스트리를 생성하고 관리합니다.

모든 가상 레지스트리 목록 조회#

히스토리

• downloads_count 및 downloaded_at이 GitLab 18.4에서 도입되었습니다.

지정된 그룹의 모든 Maven 가상 레지스트리를 반환합니다.

GET /groups/:id/-/virtual_registries/packages/maven/registries

지원되는 속성:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/registries"

응답 예시:

[
  {
    "id": 1,
    "group_id": 5,
    "name": "my-virtual-registry",
    "description": "My virtual registry",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]

가상 레지스트리 생성#

지정된 그룹의 Maven 가상 레지스트리를 생성합니다.

POST /groups/:id/-/virtual_registries/packages/maven/registries

요청 예시:

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data '{"name": "my-virtual-registry", "description": "My virtual registry"}' \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/registries"

응답 예시:

{
  "id": 1,
  "group_id": 5,
  "name": "my-virtual-registry",
  "description": "My virtual registry",
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z"
}

가상 레지스트리 조회#

지정된 Maven 가상 레지스트리를 반환합니다.

GET /virtual_registries/packages/maven/registries/:id

파라미터:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1"

응답 예시:

{
  "id": 1,
  "group_id": 5,
  "name": "my-virtual-registry",
  "description": "My virtual registry",
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z"
}

가상 레지스트리 업데이트#

지정된 Maven 가상 레지스트리를 업데이트합니다.

PATCH /virtual_registries/packages/maven/registries/:id

요청 예시:

curl --request PATCH \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"name": "my-virtual-registry", "description": "My virtual registry"}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1"

성공 시 200 OK 상태 코드를 반환합니다.

가상 레지스트리 삭제#

지정된 Maven 가상 레지스트리를 삭제합니다.

DELETE /virtual_registries/packages/maven/registries/:id

요청 예시:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1"

성공 시 204 No Content 상태 코드를 반환합니다.

가상 레지스트리의 캐시 항목 삭제#

히스토리

• GitLab 18.2에서 maven_virtual_registry라는 플래그와 함께 도입되었습니다. 기본적으로 활성화됨.

Maven 가상 레지스트리의 모든 독점 업스트림 레지스트리의 모든 캐시 항목을 삭제 예약합니다. 다른 가상 레지스트리와 연관된 업스트림 레지스트리의 캐시 항목은 삭제 예약되지 않습니다.

DELETE /virtual_registries/packages/maven/registries/:id/cache

요청 예시:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1/cache"

성공 시 204 No Content 상태 코드를 반환합니다.

업스트림 레지스트리 관리#

다음 엔드포인트를 사용하여 업스트림 Maven 레지스트리를 구성하고 관리합니다.

모든 업스트림 레지스트리 목록 조회#

히스토리

• GitLab 18.3에서 maven_virtual_registry라는 플래그와 함께 도입되었습니다. 기본적으로 활성화됨.
• upstream_name이 GitLab 18.4에서 도입되었습니다.

지정된 최상위 그룹의 모든 업스트림 Maven 레지스트리를 반환합니다.

GET /groups/:id/-/virtual_registries/packages/maven/upstreams

지원되는 속성:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/upstreams"

응답 예시:

[
  {
    "id": 1,
    "group_id": 5,
    "url": "https://repo.maven.apache.org/maven2",
    "name": "Maven Central",
    "description": "Maven Central repository",
    "cache_validity_hours": 24,
    "metadata_cache_validity_hours": 24,
    "username": "user",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z"
  }
]

생성 전 업스트림 레지스트리 연결 테스트#

히스토리

• GitLab 18.3에서 maven_virtual_registry라는 플래그와 함께 도입되었습니다. 기본적으로 활성화됨.

아직 가상 레지스트리에 추가되지 않은 Maven 업스트림 레지스트리 연결을 테스트합니다. 이 엔드포인트는 업스트림 레지스트리를 생성하기 전에 연결성과 자격 증명을 검증합니다.

POST /groups/:id/-/virtual_registries/packages/maven/upstreams/test

지원되는 속성:

테스트 워크플로#

test 엔드포인트는 제공된 업스트림 URL로 테스트 경로를 사용하여 HEAD 요청을 보내 연결성 및 인증을 검증합니다. HEAD 요청에서 받은 응답은 다음과 같이 해석됩니다:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --url "https://gitlab.example.com/api/v4/groups/5/-/virtual_registries/packages/maven/upstreams/test" \
     --data '{"url": "https://repo.maven.apache.org/maven2"}'

응답 예시:

{
  "success": true
}

가상 레지스트리의 모든 업스트림 레지스트리 목록 조회#

지정된 가상 레지스트리의 모든 업스트림 Maven 레지스트리를 반환합니다.

GET /virtual_registries/packages/maven/registries/:id/upstreams

지원되는 속성:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1/upstreams"

응답 예시:

[
  {
    "id": 1,
    "group_id": 5,
    "url": "https://repo.maven.apache.org/maven2",
    "name": "Maven Central",
    "description": "Maven Central repository",
    "cache_validity_hours": 24,
    "metadata_cache_validity_hours": 24,
    "username": "user",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z",
    "registry_upstream": {
      "id": 1,
      "registry_id": 1,
      "position": 1
    }
  }
]

업스트림 레지스트리 생성#

히스토리

• metadata_cache_validity_hours가 GitLab 18.3에서 도입되었습니다.

지정된 Maven 가상 레지스트리의 업스트림 레지스트리를 생성합니다.

POST /virtual_registries/packages/maven/registries/:id/upstreams

요청 예시:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"url": "https://repo.maven.apache.org/maven2", "name": "Maven Central", "description": "Maven Central repository", "username": <your_username>, "password": <your_password>, "cache_validity_hours": 48, "metadata_cache_validity_hours": 1}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/1/upstreams"

응답 예시:

{
  "id": 1,
  "group_id": 5,
  "url": "https://repo.maven.apache.org/maven2",
  "name": "Maven Central",
  "description": "Maven Central repository",
  "cache_validity_hours": 48,
  "metadata_cache_validity_hours": 1,
  "username": "user",
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z",
  "registry_upstream": {
    "id": 1,
    "registry_id": 1,
    "position": 1
  }
}

업스트림 레지스트리 조회#

지정된 업스트림 레지스트리를 반환합니다.

GET /virtual_registries/packages/maven/upstreams/:id

파라미터:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1"

응답 예시:

{
  "id": 1,
  "group_id": 5,
  "url": "https://repo.maven.apache.org/maven2",
  "name": "Maven Central",
  "description": "Maven Central repository",
  "cache_validity_hours": 24,
  "metadata_cache_validity_hours": 24,
  "username": "user",
  "created_at": "2024-05-30T12:28:27.855Z",
  "updated_at": "2024-05-30T12:28:27.855Z",
  "registry_upstreams": [
    {
      "id": 1,
      "registry_id": 1,
      "position": 1
    }
  ]
}

업스트림 레지스트리 업데이트#

히스토리

• metadata_cache_validity_hours가 GitLab 18.3에서 도입되었습니다.

지정된 업스트림 레지스트리를 업데이트합니다.

PATCH /virtual_registries/packages/maven/upstreams/:id

요청 예시:

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"cache_validity_hours": 72}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1"

성공 시 200 OK 상태 코드를 반환합니다.

업스트림 레지스트리 위치 업데이트#

Maven 가상 레지스트리의 순서 목록에서 업스트림 레지스트리의 위치를 업데이트합니다.

PATCH /virtual_registries/packages/maven/registry_upstreams/:id

요청 예시:

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"position": 5}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registry_upstreams/1"

성공 시 200 OK 상태 코드를 반환합니다.

업스트림 레지스트리 삭제#

지정된 업스트림 레지스트리를 삭제합니다.

DELETE /virtual_registries/packages/maven/upstreams/:id

요청 예시:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1"

성공 시 204 No Content 상태 코드를 반환합니다.

가상 레지스트리와 업스트림 레지스트리 연결#

히스토리

• GitLab 18.1에서 maven_virtual_registry라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화됨.
• GitLab 18.2에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 활성화되었습니다.

기존 업스트림 레지스트리를 지정된 Maven 가상 레지스트리와 연결합니다.

POST /virtual_registries/packages/maven/registry_upstreams

요청 예시:

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data '{"registry_id": 1, "upstream_id": 2}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registry_upstreams"

응답 예시:

{
  "id": 5,
  "registry_id": 1,
  "upstream_id": 2,
  "position": 2
}

가상 레지스트리에서 업스트림 레지스트리 연결 해제#

히스토리

• GitLab 18.1에서 maven_virtual_registry라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화됨.
• GitLab 18.2에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 활성화되었습니다.

지정된 Maven 가상 레지스트리에서 업스트림 레지스트리를 연결 해제합니다.

DELETE /virtual_registries/packages/maven/registry_upstreams/:id

요청 예시:

curl --request DELETE \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registry_upstreams/1"

성공 시 204 No Content 상태 코드를 반환합니다.

업스트림 레지스트리의 캐시 항목 삭제#

히스토리

• GitLab 18.2에서 maven_virtual_registry라는 플래그와 함께 도입되었습니다. 기본적으로 활성화됨.

지정된 업스트림 레지스트리의 모든 캐시 항목을 삭제 예약합니다.

DELETE /virtual_registries/packages/maven/upstreams/:id/cache

요청 예시:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1/cache"

성공 시 204 No Content 상태 코드를 반환합니다.

업스트림 레지스트리 연결 테스트#

히스토리

• GitLab 18.3에서 maven_virtual_registry라는 플래그와 함께 도입되었습니다. 기본적으로 활성화됨.

지정된 Maven 업스트림 레지스트리 연결을 테스트합니다.

GET /virtual_registries/packages/maven/upstreams/:id/test

테스트 작동 방식#

이 엔드포인트는 연결성 및 인증을 검증하기 위해 테스트 경로를 사용하여 업스트림 URL로 HEAD 요청을 수행합니다. 업스트림에 캐시된 아티팩트가 있으면 해당 상대 경로를 테스트에 사용합니다. 그렇지 않으면 더미 경로를 사용합니다. HEAD 요청에서 받은 응답은 다음과 같이 해석됩니다:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1/test"

응답 예시:

{
  "success": true
}

오버라이드 파라미터로 업스트림 레지스트리 연결 테스트#

히스토리

• GitLab 18.7에서 maven_virtual_registry라는 플래그와 함께 도입되었습니다. 기본적으로 활성화됨.

선택적 파라미터 오버라이드로 지정된 Maven 업스트림 레지스트리 연결을 테스트합니다.

이를 통해 업스트림 레지스트리 구성을 업데이트하기 전에 URL, 사용자 이름 또는 비밀번호에 대한 변경 사항을 테스트할 수 있습니다.

POST /virtual_registries/packages/maven/upstreams/:id/test

지원되는 속성:

테스트 작동 방식#

이 엔드포인트는 연결성 및 인증을 검증하기 위해 테스트 경로를 사용하여 업스트림 URL로 HEAD 요청을 수행합니다. 업스트림에 캐시된 아티팩트가 있으면 업스트림의 상대 경로를 테스트에 사용합니다. 그렇지 않으면 플레이스홀더 경로를 사용합니다.

테스트 동작은 제공된 파라미터에 따라 달라집니다:

• 파라미터 없음: 현재 구성(기존 URL, 사용자 이름, 비밀번호)으로 업스트림 테스트
• URL 오버라이드: 새 URL로 연결성 테스트, 사용자 이름과 비밀번호는 함께 제공하거나 둘 다 제외해야 함
• 자격 증명 오버라이드: 새 자격 증명으로 기존 URL 테스트

HEAD 요청에서 받은 응답은 다음과 같이 해석됩니다:

요청 예시 (기존 구성 테스트):

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1/test"

요청 예시 (URL 오버라이드 및 자격 증명 없음으로 테스트):

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"url": "<https://new-repo.example.com/maven2>"}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1/test"

요청 예시 (URL 및 자격 증명 오버라이드로 테스트):

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"url": "<https://new-repo.example.com/maven2>", "username": "<newuser>", "password": "<newpass>"}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1/test"

요청 예시 (자격 증명 오버라이드로 테스트):

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"username": "<newuser>", "password": "<newpass>"}' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1/test"

응답 예시:

{
  "success": true
}

캐시 항목 관리#

다음 엔드포인트를 사용하여 Maven 가상 레지스트리의 캐시 항목을 관리합니다.

모든 업스트림 레지스트리 캐시 항목 목록 조회#

지정된 Maven 업스트림 레지스트리의 모든 캐시 항목을 반환합니다.

GET /virtual_registries/packages/maven/upstreams/:id/cache_entries

지원되는 속성:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/upstreams/1/cache_entries?search=foo/bar"

응답 예시:

[
  {
    "id": "MTUgZm9vL2Jhci9teXBrZy8xLjAtU05BUFNIT1QvbXlwa2ctMS4wLVNOQVBTSE9ULmphcg==",
    "group_id": 5,
    "upstream_id": 1,
    "upstream_checked_at": "2024-05-30T12:28:27.855Z",
    "file_md5": "44f21d5190b5a6df8089f54799628d7e",
    "file_sha1": "74d101856d26f2db17b39bd22d3204021eb0bf7d",
    "size": 2048,
    "relative_path": "foo/bar/package-1.0.0.pom",
    "content_type": "application/xml",
    "upstream_etag": "\"686897696a7c876b7e\"",
    "created_at": "2024-05-30T12:28:27.855Z",
    "updated_at": "2024-05-30T12:28:27.855Z",
    "downloads_count": 6,
    "downloaded_at": "2024-06-05T14:58:32.855Z"
  }
]

업스트림 레지스트리 캐시 항목 삭제#

Maven 업스트림 레지스트리의 지정된 캐시 항목을 삭제합니다.

DELETE /virtual_registries/packages/maven/cache_entries/*id

요청 예시:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Accept: application/json" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/cache_entries/Zm9vL2Jhci9teXBrZy5wb20="

성공 시 204 No Content 상태 코드를 반환합니다.

패키지 작업 관리#

다음 엔드포인트를 사용하여 Maven 가상 레지스트리의 패키지 작업을 관리합니다.

이 엔드포인트는 REST API 인증 방법을 따르지 않습니다. 지원되는 헤더 및 토큰 유형에 대한 자세한 내용은 Maven 가상 레지스트리를 참조하세요. 문서화되지 않은 인증 방법은 향후 제거될 수 있습니다.

패키지 다운로드#

지정된 Maven 가상 레지스트리에서 패키지를 다운로드합니다. 이 리소스에 접근하려면 레지스트리로 인증해야 합니다.

GET /virtual_registries/packages/maven/:id/*path

지원되는 속성:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/1/foo/bar/mypkg/1.0-SNAPSHOT/mypkg-1.0-SNAPSHOT.jar" \
     --output mypkg-1.0-SNAPSHOT.jar

성공 시 200 OK 및 다음 응답 헤더를 반환합니다:

• x-checksum-sha1: 파일의 SHA1 체크섬
• x-checksum-md5: 파일의 MD5 체크섬
• Content-Type: 파일의 MIME 유형
• Content-Length: 바이트 단위 파일 크기

패키지 업로드#

지정된 Maven 가상 레지스트리에 패키지를 업로드합니다. 이 엔드포인트는 GitLab Workhorse에서만 접근 가능합니다.

POST /virtual_registries/packages/maven/:id/*path/upload

요청 헤더:

• Etag: 파일의 엔티티 태그
• GitLab-Workhorse-Send-Dependency-Content-Type: 파일의 콘텐츠 유형
• Upstream-GID: 대상 업스트림의 글로벌 ID

성공 시 200 OK 상태 코드를 반환합니다.