コンテナレジストリAPI

現在のプロジェクトにスコープされたCI_JOB_TOKEN の使用が GitLab 13.12 で導入されました。

このAPIドキュメントはGitLabコンテナレジストリに関するものです。

ci_job_token_scope 機能フラグが有効な場合(デフォルトでは無効になっています)、JOB-TOKEN ヘッダとして$CI_JOB_TOKEN 変数を渡すことで、CI/CD ジョブから以下のエンドポイントを利用することができます。ジョブトークンは自身のプロジェクトにのみアクセスクンできます。

GitLab RailsコンソールにアクセスできるGitLab管理者は、この機能を有効にすることができます。

有効にするには:

Feature.enable(:ci_job_token_scope)

無効化するには:

Feature.disable(:ci_job_token_scope)

コンテナレジストリの表示を変更します。

GitLab 14.2で導入されました

コンテナレジストリの閲覧者を制御します。

PUT /projects/:id/
属性種類必須説明
id整数/文字列yes認証ユーザーがアクセス可能なプロジェクトのIDまたはURLエンコードされたパス
container_registry_access_level文字列です。いいえコンテナレジストリの表示。enabled (デフ ォル ト )、privatedisabled のいずれか。

container_registry_access_level で指定可能な値の説明:

  • 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整数/文字列yes認証ユーザーがアクセス可能なプロジェクトのIDまたはURLエンコードされたパス
tagsbooleanいいえこのパラメータが true の場合、各リポジトリはレスポンスに"tags" の配列を含みます。
tags_countbooleanいいえパラメータにtrueが含まれている場合、各リポジトリはレスポンスに"tags_count" (GitLab 13.1で導入)を含みます。
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"
  },
  {
    "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"
  }
]

グループ内で

GitLab 15.0 でtagstag_count 属性を削除しました。

グループ内のレジストリリポジトリのリストを取得します。

GET /groups/:id/registry/repositories
属性種類必須説明
id整数/文字列yes認証ユーザーがアクセス可能なグループの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",
  }
]

リポジトリの詳細を取得します。

GitLab 13.6で導入されました

レジストリリポジトリの詳細を取得します。

GET /registry/repositories/:id
属性種類必須説明
id整数/文字列yes認証ユーザーがアクセス可能なレジストリリポジトリの ID。
tagsbooleanいいえパラメータがtrue として含まれている場合、レスポンスには"tags" の配列が含まれます。
tags_countbooleanいいえパラメータがtrue として含まれている場合、レスポンスには"tags_count" が含まれます。
sizebooleanいいえパラメータにtrueが含まれている場合、レスポンスには"size"が含まれます。これは、リポジトリ内のすべてのイメージの重複排除サイズです。重複排除は、同一データの余分なコピーを排除します。たとえば、同じイメージを二度アップロードしても、コンテナレジストリには一度しか保存されません。このフィールドは、GitLab.com では2021-11-04 以降に作成されたリポジトリでのみ利用できます。
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
}

レジストリリポジトリの削除

レジストリのリポジトリを削除します。

このオペレーションは非同期で実行されるため、実行に時間がかかる場合があります。

DELETE /projects/:id/registry/repositories/:repository_id
属性種類必須説明
id整数/文字列yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
repository_id整数。yesレジストリリポジトリのID。
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2"

レジストリリポジトリのタグを一覧表示します。

プロジェクト内

指定したレジストリポジトリのタグの一覧を取得します。

GET /projects/:id/registry/repositories/:repository_id/tags
属性種類必須説明
id整数/文字列yes認証ユーザーがアクセス可能なプロジェクトのIDまたはURLエンコードされたパス
repository_id整数。yesレジストリリポジトリの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整数/文字列yes認証ユーザーがアクセス可能なプロジェクトのIDまたはURLエンコードされたパス
repository_id整数。yesレジストリリポジトリのID。
tag_name文字列です。yesタグの名前。
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整数/文字列yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
repository_id整数。yesレジストリリポジトリのID。
tag_name文字列です。yesタグの名前。
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0"

このアクションはblobを削除しません。ブロブを削除してディスク領域をリサイクルするには、ガベージ・コレクションを実行してください。

レジストリリポジトリタグの一括削除

指定した条件に基づいてレジストリポジトリのタグを一括削除します。

概要については、コンテナレジストリ API を使用して * 以外のすべてのタグを削除 を参照してください。

DELETE /projects/:id/registry/repositories/:repository_id/tags
属性種類必須説明
id整数/文字列yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
repository_id整数。yesレジストリリポジトリのID。
name_regex文字列です。いいえ削除する名前のre2正規表現。すべてのタグを削除するには.*を指定します。注: name_regex は非推奨で、name_regex_deleteを使用します。 このフィールドは有効です。
name_regex_delete文字列です。yes削除する名前のre2正規表現。すべてのタグを削除するには.*を指定します。このフィールドは検証されます。
name_regex_keep文字列です。いいえ保持する名前のre2正規表現。この値はname_regex_deleteからの一致を上書きします。 このフィールドは検証されます。注意:.* に設定すると、no-op になります。
keep_n整数。いいえ指定された名前の最新のタグを保持する量。
older_than文字列です。いいえ指定された時間より古いものを削除するタグで、人間が読める形式で書かれています1h,1d,1month.

このAPIは、成功するとHTTPレスポンスステータスコード202を返し、以下のオペレーションを実行します:

  • すべてのタグを作成日順に並べます。作成日は、タグがプッシュされた時間ではなく、マニフェストが作成された時間です。
  • 指定されたname_regex_delete (または非推奨のname_regex) にマッチするタグのみを削除し、name_regex_keep にマッチするタグは残します。
  • latest という名前のタグは決して削除しません。
  • (keep_n が指定されている場合)一致する最新のタグをN個保持します。
  • X時間以上前のタグのみを削除します(older_than が指定された場合)。
  • 非同期ジョブがバックグラウンドで実行されるようにスケジュールします。

これらのオペレーションは非同期で実行されるため、実行に時間がかかることがあります。指定したコンテナリポジトリに対して、最大で1時間に1回実行できます。このアクションはblobを削除しません。ブロブを削除してディスク領域をリサイクルするには、ガベージコレクションを実行してください。

caution
GitLab.com ではコンテナレジストリの規模が大きいため、この API で削除できるタグの数は限られています。コンテナレジストリに削除するタグが大量にある場合は、その一部しか削除されず、この API を何度もコールする必要があるかもしれません。タグの自動削除を予約するには、代わりにクリーンアップポリシーを使用します。

例:

  • 正規表現(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>" "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>" "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>" "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>" "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>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags"

インスタンス全体のエンドポイント

上で説明したグループやプロジェクト固有の GitLab API のほかに、コンテナレジストリにも独自のエンドポイントがあります。これらをクエリするには、レジストリに組み込まれている仕組みに従って認証トークンを取得・使用します。

note
これらは、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":" ... "}

参照による画像タグの削除

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

定義済みの変数CI_REGISTRY_USERCI_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" \
        "https://gitlab.example.com:5050/v2/${CI_REGISTRY_IMAGE}/tags/reference/${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