コンテナレジストリAPI
- プラン: Free、Premium、Ultimate
- 提供形態: GitLab.com、GitLab 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: コンテナレジストリは、レポーターロール以上のロールを持つプロジェクトメンバーのみに表示されます。この動作は、コンテナレジストリの表示レベルが有効に設定された非公開プロジェクトの動作に似ています。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エンコードされたパス。 |
tags | ブール値 | いいえ | パラメータがtrueとして含まれている場合、各リポジトリの応答に"tags"の配列が含まれます。 |
tags_count | ブール値 | いいえ | パラメータがtrueとして含まれている場合、各リポジトリの応答に"tags_count"が含まれます。 |
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"
}
]グループ内
グループ内のレジストリリポジトリのリストを取得します。
GET /groups/:id/registry/repositories| 属性 | 型 | 必須 | 説明 |
|---|---|---|---|
id | 整数または文字列 | はい | 認証済みユーザーがアクセスできるグループのID、またはURLエンコードされたパス。 |
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| 属性 | 型 | 必須 | 説明 |
|---|---|---|---|
id | 整数または文字列 | はい | 認証済みユーザーがアクセスできるレジストリリポジトリのID。 |
tags | ブール値 | いいえ | パラメータがtrueとして含まれている場合、応答に"tags"の配列が含まれます。 |
tags_count | ブール値 | いいえ | パラメータがtrueとして含まれている場合、応答に"tags_count"が含まれます。 |
size | ブール値 | いいえ | パラメータがtrueとして含まれている場合、応答に"size"が含まれます。これは、リポジトリ内のすべてのイメージの重複排除後のサイズです。重複排除により、同一データの余分なコピーが除去されます。たとえば、イメージを2回アップロードした場合、コンテナレジストリには1つのコピーのみが保存されます。このフィールドは、GitLab.comで2021-11-04より後に作成されたリポジトリに対してのみ使用できます。 |
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| 属性 | 型 | 必須 | 説明 |
|---|---|---|---|
id | 整数または文字列 | はい | プロジェクトのIDまたはURLエンコードされたパス。 |
repository_id | 整数 | はい | レジストリリポジトリのID。 |
curl --request DELETE \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2"レジストリリポジトリのタグのリストを取得する
プロジェクト内
指定されたレジストリリポジトリのタグのリストを取得します。
オフセットページネーションは非推奨となり、キーセットページネーションが推奨のページネーション方法になりました。
GET /projects/:id/registry/repositories/:repository_id/tags| 属性 | 型 | 必須 | 説明 |
|---|---|---|---|
id | 整数または文字列 | はい | 認証済みユーザーがアクセスできるプロジェクトのID、またはURLエンコードされたパス。 |
repository_id | 整数 | はい | レジストリリポジトリのID。 |
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| 属性 | 型 | 必須 | 説明 |
|---|---|---|---|
id | 整数または文字列 | はい | 認証済みユーザーがアクセスできるプロジェクトのID、またはURLエンコードされたパス。 |
repository_id | 整数 | はい | レジストリリポジトリのID。 |
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| 属性 | 型 | 必須 | 説明 |
|---|---|---|---|
id | 整数または文字列 | はい | プロジェクトのIDまたはURLエンコードされたパス。 |
repository_id | 整数 | はい | レジストリリポジトリのID。 |
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"この操作ではblobは削除されません。ディスク容量を回復させるには、ガベージコレクションを実行します。
レジストリリポジトリのタグを一括削除する
指定された条件に基づいて、レジストリリポジトリのタグを一括削除します。
概要については、コンテナレジストリAPIを使用して、*以外のすべてのタグを削除するを参照してください。
DELETE /projects/:id/registry/repositories/:repository_id/tags| 属性 | 型 | 必須 | 説明 |
|---|---|---|---|
id | 整数または文字列 | はい | プロジェクトのIDまたはURLエンコードされたパス。 |
repository_id | 整数 | はい | レジストリリポジトリのID。 |
keep_n | 整数 | いいえ | 保持する指定された名前の最新のタグの数。 |
name_regex | 文字列 | いいえ | 削除する名前のre2正規表現。すべてのタグを削除するには、.*を指定します。注： name_regexは非推奨となり、name_regex_deleteが推奨されます。このフィールドは検証されます。 |
name_regex_delete | 文字列 | はい | 削除する名前のre2正規表現。すべてのタグを削除するには、.*を指定します。このフィールドは検証されます。 |
name_regex_keep | 文字列 | いいえ | 保持する名前のre2正規表現。この値は、name_regex_deleteからの一致を上書きします。このフィールドは検証されます。注: .*に設定すると、何も実行されません。 |
older_than | 文字列 | いいえ | 指定された時刻より前の削除対象のタグ。1h、1d、1monthなど、人間が読める形式で記述されています。 |
このAPIは成功した場合、HTTP応答ステータスコード202を返し、次の操作を実行します:
- すべてのタグを作成日順に並べ替えます。作成日は、タグのプッシュ時刻ではなく、manifestの作成時刻です。
- 指定された
name_regex_delete（または非推奨のname_regex）に一致するタグのみを削除し、name_regex_keepに一致するものは保持します。 latestという名前のタグは削除しません。- N個の最新の一致するタグを保持します（
keep_nが指定されている場合）。 - X時間以上前のタグのみを削除します（
older_thanが指定されている場合）。 - 保護タグは除外します。
- バックグラウンドで実行される非同期のジョブをスケジュールします。
これらの操作は非同期で実行されるため、実行されるまでに時間がかかる場合があります。操作は、指定されたコンテナリポジトリに対して1時間に1回まで実行できます。
この操作ではblobは削除されません。ディスク容量を回復させるには、ガベージコレクションを実行します。
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>" \ --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アプリケーションのプロジェクトアクセストークンまたはパーソナルアクセストークンとは異なります。
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":" ... "}参照でイメージタグを削除する
DELETE http(s)://${CI_REGISTRY}/v2/${CI_REGISTRY_IMAGE}/tags/reference/${CI_COMMIT_SHORT_SHA}事前定義されたCI_REGISTRY_USER変数とCI_REGISTRY_PASSWORD変数で取得したトークンを使用すると、GitLabインスタンスの参照によるコンテナイメージタグを削除できます。tag_deleteコンテナレジストリ機能を有効にする必要があります。
$ 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/_catalogGitLabインスタンス上のすべてのコンテナリポジトリのリストを取得するには、管理者の認証情報が必要です:
$ 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"