컨테이너 레지스트리 API

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

이 API 엔드포인트를 사용하여 GitLab 컨테이너 레지스트리를 작업할 수 있습니다.

이 엔드포인트로 CI/CD 작업에서 $CI_JOB_TOKEN 변수를 JOB-TOKEN 헤더로 전송하여 인증할 수 있습니다. 작업 토큰은 생성된 파이프라인의 특정 프로젝트의 컨테이너 레지스트리에만 액세스할 수 있습니다.

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

이것은 컨테이너 레지스트리를 볼 수 있는 사용자를 제어합니다. 

PUT /projects/:id/
속성 유형 필수 설명
id 정수/문자열 예 인증된 사용자가 액세스할 수 있는 프로젝트의 ID 또는 URL 인코딩된 경로
container_registry_access_level 문자열 아니오 컨테이너 레지스트리의 원하는 가시성 중 하나. enabled (기본), private, 또는 disabled 중 하나.

container_registry_access_level의 가능한 값에 대한 설명:

  • enabled (기본): 컨테이너 레지스트리는 프로젝트에 액세스할 수 있는 모든 사람에게 표시됩니다. 프로젝트가 공개되어 있으면 컨테이너 레지스트리도 공개됩니다. 프로젝트가 내부 또는 비공개이면 컨테이너 레지스트리도 내부 또는 비공개됩니다.
  • private: 컨테이너 레지스트리는 ‘리포터’ 역할 이상의 프로젝트 멤버만 볼 수 있습니다. 이 동작은 enabled로 설정된 컨테이너 레지스트리의 비공개 프로젝트와 유사합니다.
  • 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",
  ...
}

컨테이너 레지스트리 페이지네이션

API 결과가 페이지 나누기됨으로 인해 기본적으로 GET 요청은 한 번에 20개의 결과를 반환합니다.

레지스트리 리포지토리 목록

프로젝트 내

프로젝트 내의 레지스트리 리포지토리 목록을 가져옵니다. 

GET /projects/:id/registry/repositories
속성 유형 필수 설명
id 정수/문자열 예 인증된 사용자가 액세스할 수 있는 프로젝트의 ID 또는 URL 인코딩된 경로 
curl --header "PRIVATE-TOKEN: <your_access_token>" "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"
  }
]

그룹 내

그룹 내의 레지스트리 리포지토리 목록을 가져옵니다. 

GET /groups/:id/registry/repositories
속성 유형 필수 설명
id 정수/문자열 예 인증된 사용자가 액세스할 수 있는 그룹의 ID 또는 URL 인코딩된 경로 
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     "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
속성 유형 필수 설명
id 정수/문자열 예 인증된 사용자가 액세스할 수 있는 레지스트리 리포지토리의 ID
tags 부울형 아니오 매개변수가 true로 포함되면 응답에 "tags" 배열이 포함됩니다.
tags_count 부울형 아니오 매개변수가 true로 포함되면 응답에 "tags_count"가 포함됩니다.
size 부울형 아니오 매개변수가 true로 포함되면 응답에 "size"가 포함됩니다. 이것은 리포지토리 내 모든 이미지의 중복 제거된 크기입니다. 중복 제거는 동일한 데이터의 추가 사본을 제거합니다. 예를 들어 동일한 이미지를 두 번 업로드하면 컨테이너 레지스트리는 하나의 사본만 저장합니다.이 필드는 2021-11-04 이후에 생성된 리포지토리에 대해서만 GitLab.com에서 사용할 수 있습니다. 
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     "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
속성 타입 필수 설명
id 정수/문자열 예 프로젝트의 ID 또는 URL-인코딩된 경로입니다.
repository_id 정수 예 레지스트리 저장소의 ID입니다. 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2"

레지스트리 저장소 태그 목록

프로젝트 내에서

  • GitLab 16.10에서 소개된 키셋 페이지네이션은 GitLab.com 전용입니다.

지정된 레지스트리 저장소의 태그 목록을 가져옵니다. 

GET /projects/:id/registry/repositories/:repository_id/tags
속성 타입 필수 설명
id 정수/문자열 예 인증된 사용자가 액세스할 수 있는 프로젝트의 ID 또는 URL-인코딩된 경로입니다.
repository_id 정수 예 레지스트리 저장소의 ID입니다. 
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     "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
속성 타입 필수 설명
id 정수/문자열 예 인증된 사용자가 액세스할 수 있는 프로젝트의 ID 또는 URL-인코딩된 경로입니다.
repository_id 정수 예 레지스트리 저장소의 ID입니다.
tag_name 문자열 예 태그의 이름입니다. 
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     "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
}

레지스트리 저장소 태그 삭제

레지스트리 저장소 태그를 삭제합니다. 

DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name
속성 타입 필수 설명
id 정수/문자열 예 URL-인코딩된 경로의 프로젝트 ID입니다.
repository_id 정수 예 레지스트리 저장소의 ID입니다.
tag_name 문자열 예 태그의 이름입니다. 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0"

이 작업은 블롭을 삭제하지 않습니다. 디스크 공간을 재활용하려면 가비지 수집을 실행하세요.

cURL을 사용하여 +을 포함하는 정규 표현식 사용하기

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

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

인스턴스 전역 엔드포인트

위에서 설명한 그룹 및 프로젝트별 GitLab API와 별도로 컨테이너 레지스트리에는 자체 엔드포인트가 있습니다. 이를 조회하려면 인증 토큰을 얻고 사용하기 위해 레지스트리의 내장된 메커니즘을 따르세요.

참고: 이는 GitLab 애플리케이션의 프로젝트 또는 개인 액세스 토큰과는 다릅니다.

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}" \
        "https://gitlab.example.com/jwt/auth?service=container_registry&scope=${SCOPE}"
{"token":" ... "}

참조에 의해 이미지 태그 삭제

  • Endpoint v2/<name>/manifests/<tag>소개됨 및 endpoint v2/<name>/tags/reference/<tag> 사용 중단됨 - GitLab 16.4에서. 
DELETE http(s)://${CI_REGISTRY}/v2/${CI_REGISTRY_IMAGE}/tags/reference/${CI_COMMIT_SHORT_SHA}

GitLab 인스턴스에서 참조에 의해 컨테이너 이미지 태그를 삭제하려면 미리 정의된 CI_REGISTRY_USER 및 CI_REGISTRY_PASSWORD 변수로 검색한 토큰을 사용할 수 있습니다. tag_delete 컨테이너 레지스트리 기능를 활성화해야 합니다. 

$ curl  --request DELETE --header "Authorization: Bearer <token_from_above>" \
        --header "Accept: application/vnd.docker.distribution.manifest.v2+json" \
        "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>" \
        "https://gitlab.example.com/jwt/auth?service=container_registry&scope=${SCOPE}"
{"token":" ... "}

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