이 API를 사용하여 GitLab 컨테이너 레지스트리를 관리합니다.

CI/CD Job에서 이 엔드포인트로 인증하려면 $CI_JOB_TOKEN 변수를 JOB-TOKEN 헤더로 전달합니다. Job 토큰은 파이프라인을 생성한 프로젝트의 컨테이너 레지스트리에만 액세스할 수 있습니다.

컨테이너 레지스트리 가시성 변경#

지정된 프로젝트의 컨테이너 레지스트리 가시성을 변경합니다.

PUT /projects/:id/

container_registry_access_level의 가능한 값 설명:

• enabled(기본값): 컨테이너 레지스트리는 프로젝트에 액세스하는 모든 사람에게 표시됩니다. 프로젝트가 공개이면 컨테이너 레지스트리도 공개입니다. 프로젝트가 내부 또는 비공개이면 컨테이너 레지스트리도 내부 또는 비공개입니다.
• private: 컨테이너 레지스트리는 Reporter 권한 이상의 프로젝트 멤버에게만 표시됩니다. 이 동작은 컨테이너 레지스트리 가시성이 활성화된 비공개 프로젝트의 동작과 유사합니다.
• disabled: 컨테이너 레지스트리가 비활성화됩니다.

이 설정이 사용자에게 부여하는 권한에 대한 자세한 내용은 컨테이너 레지스트리 가시성 권한을 참조하세요.

curl --request PUT "https://gitlab.example.com/api/v4/projects/5/" \
  --header 'PRIVATE-TOKEN: <your_access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "container_registry_access_level": "private"
  }'

응답 예시:

{
  "id": 5,
  "name": "Project 5",
  "container_registry_access_level": "private",
  ...
}

모든 레지스트리 리포지터리 나열#

프로젝트 내#

지정된 프로젝트의 모든 레지스트리 리포지터리를 나열합니다.

응답은 페이지가 나뉘며 기본적으로 20개의 결과를 반환합니다.

GET /projects/:id/registry/repositories

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/registry/repositories"

응답 예시:

[
  {
    "id": 1,
    "name": "",
    "path": "group/project",
    "project_id": 9,
    "location": "gitlab.example.com:5000/group/project",
    "created_at": "2019-01-10T13:38:57.391Z",
    "cleanup_policy_started_at": "2020-01-10T15:40:57.391Z",
    "status": null
  },
  {
    "id": 2,
    "name": "releases",
    "path": "group/project/releases",
    "project_id": 9,
    "location": "gitlab.example.com:5000/group/project/releases",
    "created_at": "2019-01-10T13:39:08.229Z",
    "cleanup_policy_started_at": "2020-08-17T03:12:35.489Z",
    "status": "delete_ongoing"
  }
]

그룹 내#

히스토리

• GitLab 15.0에서 tags 및 tag_count 속성이 제거되었습니다.

지정된 그룹의 모든 레지스트리 리포지터리를 나열합니다.

응답은 페이지가 나뉘며 기본적으로 20개의 결과를 반환합니다.

GET /groups/:id/registry/repositories

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/2/registry/repositories"

응답 예시:

[
  {
    "id": 1,
    "name": "",
    "path": "group/project",
    "project_id": 9,
    "location": "gitlab.example.com:5000/group/project",
    "created_at": "2019-01-10T13:38:57.391Z",
    "cleanup_policy_started_at": "2020-08-17T03:12:35.489Z",
  },
  {
    "id": 2,
    "name": "",
    "path": "group/other_project",
    "project_id": 11,
    "location": "gitlab.example.com:5000/group/other_project",
    "created_at": "2019-01-10T13:39:08.229Z",
    "cleanup_policy_started_at": "2020-01-10T15:40:57.391Z",
  }
]

단일 리포지터리 세부 정보 검색#

지정된 레지스트리 리포지터리의 세부 정보를 검색합니다.

GET /registry/repositories/:id

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/registry/repositories/2?tags=true&tags_count=true&size=true"

응답 예시:

{
  "id": 2,
  "name": "",
  "path": "group/project",
  "project_id": 9,
  "location": "gitlab.example.com:5000/group/project",
  "created_at": "2019-01-10T13:38:57.391Z",
  "cleanup_policy_started_at": "2020-08-17T03:12:35.489Z",
  "tags_count": 1,
  "tags": [
    {
      "name": "0.0.1",
      "path": "group/project:0.0.1",
      "location": "gitlab.example.com:5000/group/project:0.0.1"
    }
  ],
  "size": 2818413,
  "status": "delete_scheduled"
}

레지스트리 리포지터리 삭제#

레지스트리의 지정된 리포지터리를 삭제합니다.

이 작업은 비동기적으로 실행되며 실행되는 데 약간의 시간이 걸릴 수 있습니다.

DELETE /projects/:id/registry/repositories/:repository_id

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2"

모든 레지스트리 리포지터리 태그 나열#

프로젝트 내#

히스토리

• GitLab.com 전용으로 GitLab 16.10에서 키셋 페이지네이션이 도입되었습니다.

지정된 레지스트리 리포지터리의 모든 태그를 나열합니다.

응답은 페이지가 나뉘며 기본적으로 20개의 결과를 반환합니다.

GET /projects/:id/registry/repositories/:repository_id/tags

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"

응답 예시:

[
  {
    "name": "A",
    "path": "group/project:A",
    "location": "gitlab.example.com:5000/group/project:A"
  },
  {
    "name": "latest",
    "path": "group/project:latest",
    "location": "gitlab.example.com:5000/group/project:latest"
  }
]

레지스트리 리포지터리 태그 세부 정보 검색#

지정된 레지스트리 리포지터리 태그의 세부 정보를 검색합니다.

GET /projects/:id/registry/repositories/:repository_id/tags/:tag_name

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0"

응답 예시:

{
  "name": "v10.0.0",
  "path": "group/project:latest",
  "location": "gitlab.example.com:5000/group/project:latest",
  "revision": "e9ed9d87c881d8c2fd3a31b41904d01ba0b836e7fd15240d774d811a1c248181",
  "short_revision": "e9ed9d87c",
  "digest": "sha256:c3490dcf10ffb6530c1303522a1405dfaf7daecd8f38d3e6a1ba19ea1f8a1751",
  "created_at": "2019-01-06T16:49:51.272+00:00",
  "total_size": 350224384
}

레지스트리 리포지터리 태그 삭제#

지정된 컨테이너 레지스트리 리포지터리 태그를 삭제합니다.

태그가 프로젝트의 보호 규칙과 일치하는 경우 엔드포인트는 403 Forbidden 오류를 반환합니다. 태그 보호 규칙에 대한 자세한 내용은 보호된 컨테이너 태그를 참조하세요.

DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0"

이 작업은 블롭을 삭제하지 않습니다. 디스크 공간을 회수하려면 가비지 컬렉션을 실행하세요.

레지스트리 리포지터리 태그 일괄 삭제#

지정된 기준에 따라 레지스트리 리포지터리 태그를 일괄 삭제합니다.

개요는 컨테이너 레지스트리 API를 사용하여 *를 제외한 모든 태그 삭제를 참조하세요.

DELETE /projects/:id/registry/repositories/:repository_id/tags

이 API가 성공하면 HTTP 응답 상태 코드 202를 반환하고 다음 작업을 수행합니다:

• 모든 태그를 생성 날짜별로 정렬합니다. 생성 날짜는 태그 푸시 시간이 아닌 매니페스트 생성 시간입니다.
• 주어진 name_regex_delete(또는 사용 중단된 name_regex)와 일치하는 태그만 제거하고 name_regex_keep와 일치하는 것은 유지합니다.
• latest라는 이름의 태그는 절대 제거하지 않습니다.
• N개의 최신 일치 태그를 유지합니다(keep_n이 지정된 경우).
• X 시간량보다 오래된 태그만 제거합니다(older_than이 지정된 경우).
• 보호된 태그는 제외합니다.
• 백그라운드에서 실행할 비동기 Job을 예약합니다.

이러한 작업은 비동기적으로 실행되며 실행되는 데 시간이 걸릴 수 있습니다. 특정 컨테이너 리포지터리에 대해 시간당 최대 한 번 실행할 수 있습니다.

이 작업은 블롭을 삭제하지 않습니다. 디스크 공간을 회수하려면 가비지 컬렉션을 실행하세요.

예시:

• 정규식(Git SHA)과 일치하는 태그 이름을 제거하고 항상 최소 5개를 유지하며 2일보다 오래된 것을 제거합니다:

  curl --request DELETE \
    --data 'name_regex_delete=[0-9a-z]{40}' \
    --data 'keep_n=5' \
    --data 'older_than=2d' \
    --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"
  

• 모든 태그를 제거하지만 항상 최신 5개는 유지합니다:

  curl --request DELETE \
    --data 'name_regex_delete=.*' \
    --data 'keep_n=5' \
    --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"
  

• 모든 태그를 제거하지만 항상 stable로 시작하는 태그는 유지합니다:

  curl --request DELETE \
    --data 'name_regex_delete=.*' \
    --data 'name_regex_keep=stable.*' \
    --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"
  

• 1개월보다 오래된 모든 태그를 제거합니다:

  curl --request DELETE \
    --data 'name_regex_delete=.*' \
    --data 'older_than=1month' \
    --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"
  

+가 포함된 정규식에서 cURL 사용#

cURL을 사용할 때, 정규식의 + 문자는 GitLab Rails 백엔드에서 올바르게 처리되려면 URL 인코딩되어야 합니다. 예를 들어:

curl --request DELETE \
  --data-urlencode 'name_regex_delete=dev-.+' \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"

인스턴스 전체 엔드포인트#

앞서 설명한 그룹별 및 프로젝트별 GitLab API 외에도 컨테이너 레지스트리에는 자체 엔드포인트가 있습니다. 이를 쿼리하려면 레지스트리의 내장 메커니즘을 따라 인증 토큰을 획득하고 사용합니다.

GitLab에서 토큰 획득#

GET ${CI_SERVER_URL}/jwt/auth?service=container_registry&scope=*

유효한 토큰을 검색하려면 올바른 범위와 액션을 지정해야 합니다:

$ SCOPE="repository:${CI_REGISTRY_IMAGE}:delete" #or push,pull

$ curl --request GET \
    --user "${CI_REGISTRY_USER}:${CI_REGISTRY_PASSWORD}" \
    --url "https://gitlab.example.com/jwt/auth?service=container_registry&scope=${SCOPE}"
{"token":" ... "}

참조로 이미지 태그 삭제#

히스토리

• GitLab 16.4에서 엔드포인트 v2//manifests/가 도입되고 엔드포인트 v2//tags/reference/가 사용 중단되었습니다.

DELETE http(s)://${CI_REGISTRY}/v2/${CI_REGISTRY_IMAGE}/tags/reference/${CI_COMMIT_SHORT_SHA}

미리 정의된 CI_REGISTRY_USER와 CI_REGISTRY_PASSWORD 변수로 검색한 토큰을 사용하여 GitLab 인스턴스에서 참조로 컨테이너 이미지 태그를 삭제할 수 있습니다. tag_delete Container-Registry-Feature가 활성화되어야 합니다.

$ curl --request DELETE \
    --header "Authorization: Bearer <token_from_above>" \
    --header "Accept: application/vnd.docker.distribution.manifest.v2+json" \
    --url "https://gitlab.example.com:5050/v2/${CI_REGISTRY_IMAGE}/manifests/${CI_COMMIT_SHORT_SHA}"

모든 컨테이너 리포지터리 나열#

GET http(s)://${CI_REGISTRY}/v2/_catalog

GitLab 인스턴스의 모든 컨테이너 리포지터리를 나열하려면 관리자 자격 증명이 필요합니다:

$ SCOPE="registry:catalog:*"

$ curl --request GET \
    --user "<admin-username>:<admin-password>" \
    --url "https://gitlab.example.com/jwt/auth?service=container_registry&scope=${SCOPE}"
{"token":" ... "}

$ curl --header "Authorization: Bearer <token_from_above>" \
    --url "https://gitlab.example.com:5050/v2/_catalog"