Help us learn about your current experience with the documentation. Take the survey.

容器注册表 API

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

使用这些 API 端点来处理 GitLab 容器注册表。

您可以通过传递 $CI_JOB_TOKEN 变量作为 JOB-TOKEN 头部，从 CI/CD 作业中对这些端点进行身份验证。作业令牌只能访问创建该流水线的项目的容器注册表。

更改容器注册表的可见性

此设置控制谁可以查看容器注册表。

PUT /projects/:id/
属性 类型 必需 描述
id integer/string yes 经过身份验证的用户可访问的项目 ID 或 URL 编码的项目路径。
container_registry_access_level string no 容器注册表的期望可见性。可选值为 enabled（默认）、private 或 disabled。

container_registry_access_level 可能值的说明：

  • enabled（默认）：容器注册表对有权访问项目的所有人可见。 如果项目是公开的，容器注册表也是公开的。如果项目是内部或私有的， 容器注册表也是内部或私有的。
  • private：容器注册表仅对具有 Reporter 角色或更高级别的项目成员可见。 此行为类似于将容器注册表可见性设置为 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",
  ...
}

容器注册表分页

默认情况下，GET 请求一次返回 20 个结果，因为 API 结果是分页的。

列出注册表仓库

在项目中

获取项目中的注册表仓库列表。

GET /projects/:id/registry/repositories
属性 类型 必需 描述
id integer/string yes 经过身份验证的用户可访问的项目 ID 或 URL 编码的项目路径。
tags boolean no 如果参数包含为 true，则每个仓库在响应中包含一个 "tags" 数组。
tags_count boolean no 如果参数包含为 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 integer/string yes 经过身份验证的用户可访问的组 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 integer/string yes 经过身份验证的用户可访问的注册表仓库 ID。
tags boolean no 如果参数包含为 true，则响应包含一个 "tags" 数组。
tags_count boolean no 如果参数包含为 true，则响应包含 "tags_count"。
size boolean no 如果参数包含为 true，则响应包含 "size"。这是仓库中所有镜像的去重大小。去重会消除相同数据的额外副本。例如，如果您上传相同的镜像两次，容器注册表只存储一个副本。此字段仅在 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 integer/string yes 项目 ID 或 URL 编码的项目路径。
repository_id integer yes 注册表仓库的 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 integer/string yes 经过身份验证的用户可访问的项目 ID 或 URL 编码的项目路径。
repository_id integer yes 注册表仓库的 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 integer/string yes 经过身份验证的用户可访问的项目 ID 或 URL 编码的项目路径。
repository_id integer yes 注册表仓库的 ID。
tag_name string yes 标签的名称。 
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 错误。 有关标签保护规则的更多信息，请参阅受保护的容器标签。

DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name
属性 类型 必需 描述
id integer/string yes 项目 ID 或 URL 编码的项目路径。
repository_id integer yes 注册表仓库的 ID。
tag_name string yes 标签的名称。 
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 integer/string yes 项目 ID 或 URL 编码的项目路径。
repository_id integer yes 注册表仓库的 ID。
name_regex string no 要删除的名称的 re2 正则表达式。要删除所有标签，请指定 .*。注意：name_regex 已被弃用，推荐使用 name_regex_delete。此字段会进行验证。
name_regex_delete string yes 要删除的名称的 re2 正则表达式。要删除所有标签，请指定 .*。此字段会进行验证。
name_regex_keep string no 要保留的名称的 re2 正则表达式。此值会覆盖 name_regex_delete 的任何匹配项。此字段会进行验证。注意：设置为 .* 会导致无操作。
keep_n integer no 要保留的给定名称的最新标签数量。
older_than string no 删除比给定时间更早的标签，以人类可读的形式编写，如 1h、1d、1month。

如果成功，此 API 返回 HTTP 响应状态码 202，并执行以下操作：

  • 它按创建日期对所有标签进行排序。创建日期是清单创建的时间，而不是标签推送的时间。
  • 它只删除匹配给定 name_regex_delete（或已弃用的 name_regex）的标签，保留匹配 name_regex_keep 的任何标签。
  • 它从不删除名为 latest 的标签。
  • 它保留 N 个最新的匹配标签（如果指定了 keep_n）。
  • 它只删除比 X 时间更早的标签（如果指定了 older_than）。
  • 它排除受保护的标签。
  • 它安排异步作业在后台执行。

这些操作是异步执行的，可能需要一些时间才能完成。 对于给定的容器仓库，您最多可以每小时运行一次此操作。

此操作不会删除 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 时，正则表达式中的 + 字符必须进行 URL 编码， 以便 GitLab Rails 后端正确处理。例如：

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 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"