{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

使用这些 API 端点来操作 极狐GitLab 容器注册表。

你可以通过在 CI/CD 作业中传递 $CI_JOB_TOKEN 变量作为 JOB-TOKEN 头来验证这些端点。作业令牌仅能访问创建流水线的项目的容器注册表。

更改容器注册表的可见性

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

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

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",
  ...
}

容器注册表分页

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

列出注册表仓库

在项目中

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

GET /projects/:id/registry/repositories
属性 类型 必需 描述
id integer/string 是 经过身份验证的用户可以访问的项目的 ID 或 URL 编码路径。
tags boolean 否 如果参数包含为 true，则响应中的每个仓库都包含一个 "tags" 数组。
tags_count boolean 否 如果参数包含为 true，则响应中的每个仓库都包含 "tags_count"。 
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"
  }
]

在群组中

{{< history >}}

  • 在极狐GitLab 15.0 中 移除 tags 和 tag_count 属性。

{{< /history >}}

获取群组中注册表仓库的列表。

GET /groups/:id/registry/repositories
属性 类型 必需 描述
id integer/string 是 经过身份验证的用户可以访问的群组的 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 integer/string 是 经过身份验证的用户可以访问的注册表仓库的 ID。
tags boolean 否 如果参数包含为 true，则响应中包含一个 "tags" 数组。
tags_count boolean 否 如果参数包含为 true，则响应中包含 "tags_count"。
size boolean 否 如果参数包含为 true，则响应中包含 "size"。这是仓库内所有镜像的去重大小。去重消除了相同数据的额外副本。例如，如果你上传相同的镜像两次，容器注册表仅存储一个副本。此字段仅适用于 JihuLab.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,
  "status": "delete_scheduled"
}

删除注册表仓库

删除注册表中的仓库。

此操作是异步执行的，可能需要一些时间才能执行。

DELETE /projects/:id/registry/repositories/:repository_id
属性 类型 必需 描述
id integer/string 是 项目的 ID 或 URL 编码路径。
repository_id integer 是 注册表仓库的 ID。 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2"

列出注册表仓库标签

在项目中

{{< history >}}

  • 在 JihuLab.com 中的极狐GitLab 16.10 引入键集分页。

{{< /history >}}

获取给定注册表仓库的标签列表。

{{< alert type=”note” >}}

偏移分页已弃用，现在键集分页是首选分页方法。

{{< /alert >}}

GET /projects/:id/registry/repositories/:repository_id/tags
属性 类型 必需 描述
id integer/string 是 经过身份验证的用户可以访问的项目的 ID 或 URL 编码路径。
repository_id integer 是 注册表仓库的 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 integer/string 是 经过身份验证的用户可以访问的项目的 ID 或 URL 编码路径。
repository_id integer 是 注册表仓库的 ID。
tag_name string 是 标签的名称。 
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
}

删除注册表仓库标签

删除容器注册表仓库标签。

如果标签与项目中的任何保护规则匹配，端点会返回 403 错误。有关标签保护规则的更多信息，请参阅 受保护的容器标签。

DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name
属性 类型 必需 描述
id integer/string 是 项目的 ID 或 URL 编码路径。
repository_id integer 是 注册表仓库的 ID。
tag_name string 是 标签的名称。 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0"

此操作不会删除 blobs。要回收磁盘空间，请 运行垃圾回收。

批量删除注册表仓库标签

根据给定标准批量删除注册表仓库标签。

概览请参阅 使用容器注册表 API 删除除 * 之外的所有标签。

DELETE /projects/:id/registry/repositories/:repository_id/tags
属性 类型 必需 描述
id integer/string 是 项目的 ID 或 URL 编码路径。
repository_id integer 是 注册表仓库的 ID。
name_regex string 否 要删除名称的 re2 正则表达式。要删除所有标签，请指定 .*。 注意： name_regex 已弃用，建议使用 name_regex_delete。此字段经过验证。
name_regex_delete string 是 要删除名称的 re2 正则表达式。要删除所有标签，请指定 .*。此字段经过验证。
name_regex_keep string 否 要保留名称的 re2 正则表达式。此值覆盖 name_regex_delete 的任何匹配项。此字段经过验证。注意：设置为 .* 会导致无操作。
keep_n integer 否 要保留的指定名称的最新标签数量。
older_than string 否 要删除的比给定时间更旧的标签，采用人类可读形式 1h、1d、1month。

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

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

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

此操作不会删除 blobs。要回收磁盘空间，请 运行垃圾回收。

{{< alert type=”warning” >}}

由于容器注册表的规模，极狐GitLab .com 限制了此 API 删除的标签数量。如果你的容器注册表有大量标签需要删除，只有其中的一部分会被删除，你可能需要多次调用此 API。要安排标签自动删除，请使用 清理策略 代替。

{{< /alert >}}

示例：

  • 删除名称符合正则表达式（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 时，正则表达式中的 + 字符必须是 URL 编码的，以便极狐GitLab Rails 后端正确处理。例如：

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，容器注册表还有自己的端点。要查询这些，请遵循注册表的内置机制来获取和使用 身份验证令牌。

{{< alert type=”note” >}}

这些与极狐GitLab 应用程序中的项目或个人访问令牌不同。

{{< /alert >}}

从极狐GitLab 获取令牌 

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

你必须指定正确的作用域和操作来检索有效令牌：

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

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

按引用删除镜像标签

{{< history >}}

  • 在极狐GitLab 16.4 中引入 v2/<name>/manifests/<tag> 端点并弃用 v2/<name>/tags/reference/<tag> 端点。

{{< /history >}}

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