Back to Details

gitlab-container

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Container Registry Skill

GitLab容器镜像仓库操作技能

Container registry management for GitLab using 
glab api
raw endpoint calls.
使用
glab api
原生端点调用管理GitLab容器镜像仓库。

Quick Reference

快速参考

OperationCommand PatternRisk
List repositories
glab api projects/:id/registry/repositories
-
Get repository
glab api projects/:id/registry/repositories/:repo_id
-
Delete repository
glab api projects/:id/registry/repositories/:repo_id -X DELETE
⚠️⚠️⚠️
List tags
glab api projects/:id/registry/repositories/:repo_id/tags
-
Get tag
glab api projects/:id/registry/repositories/:repo_id/tags/:tag
-
Delete tag
glab api projects/:id/registry/repositories/:repo_id/tags/:tag -X DELETE
⚠️⚠️
Bulk delete tags
glab api projects/:id/registry/repositories/:repo_id/tags -X DELETE -f ...
⚠️⚠️⚠️
Risk Legend: - Safe | ⚠️ Caution | ⚠️⚠️ Warning | ⚠️⚠️⚠️ Danger
操作命令模板风险级别
列出容器镜像仓库
glab api projects/:id/registry/repositories
-
获取镜像仓库详情
glab api projects/:id/registry/repositories/:repo_id
-
删除镜像仓库
glab api projects/:id/registry/repositories/:repo_id -X DELETE
⚠️⚠️⚠️
列出镜像标签
glab api projects/:id/registry/repositories/:repo_id/tags
-
获取标签详情
glab api projects/:id/registry/repositories/:repo_id/tags/:tag
-
删除单个标签
glab api projects/:id/registry/repositories/:repo_id/tags/:tag -X DELETE
⚠️⚠️
批量删除标签
glab api projects/:id/registry/repositories/:repo_id/tags -X DELETE -f ...
⚠️⚠️⚠️
风险级别说明: - 安全 | ⚠️ 注意 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

When to Use This Skill

何时使用此技能

ALWAYS use when:
  • User mentions "container", "registry", "docker image", "container image"
  • User wants to list or delete Docker tags
  • User mentions "image cleanup", "registry cleanup"
  • User wants to view container repository information
NEVER use when:
  • User wants to build/push Docker images (use CI/CD or docker CLI)
  • User wants to run containers (use docker CLI or orchestrator)
  • User wants package registry (different API)
务必在以下场景使用：
  • 用户提及“容器”、“镜像仓库”、“Docker镜像”、“容器镜像”
  • 用户需要列出或删除Docker标签
  • 用户提及“镜像清理”、“仓库清理”
  • 用户需要查看容器镜像仓库信息
切勿在以下场景使用：
  • 用户需要构建/推送Docker镜像（请使用CI/CD或Docker CLI）
  • 用户需要运行容器（请使用Docker CLI或编排工具）
  • 用户需要操作包仓库（使用不同的API）

API Prerequisites

API前置条件

Required Token Scopes: 
read_registry
, 
write_registry
(for delete operations), or 
api
Permissions:
  • Read registry: Reporter+
  • Delete images: Developer+ (or Maintainer depending on settings)
Note: Container Registry must be enabled for the project.
所需令牌权限范围: 
read_registry
、
write_registry
（用于删除操作）或
api
权限要求:
  • 读取镜像仓库：Reporter及以上角色
  • 删除镜像：Developer及以上角色（或根据设置需要Maintainer角色）
注意: 项目必须已启用容器镜像仓库。

Available Commands

可用命令

List Container Repositories

列出容器镜像仓库

bash
undefined
bash
undefined

List all repositories in project

列出项目中所有镜像仓库

glab api projects/123/registry/repositories --method GET
glab api projects/123/registry/repositories --method GET

With pagination

分页列出

glab api projects/123/registry/repositories --paginate
glab api projects/123/registry/repositories --paginate

Include tags count

包含标签数量

glab api "projects/123/registry/repositories?tags_count=true" --method GET
glab api "projects/123/registry/repositories?tags_count=true" --method GET

Using project path

使用项目路径

glab api "projects/$(echo 'mygroup/myproject' | jq -Rr @uri)/registry/repositories"
undefined
glab api "projects/$(echo 'mygroup/myproject' | jq -Rr @uri)/registry/repositories"
undefined

Get Repository Details

获取镜像仓库详情

bash
undefined
bash
undefined

Get specific repository

获取指定镜像仓库详情

glab api projects/123/registry/repositories/456 --method GET
glab api projects/123/registry/repositories/456 --method GET

With tags count

包含标签数量

glab api "projects/123/registry/repositories/456?tags_count=true" --method GET
undefined
glab api "projects/123/registry/repositories/456?tags_count=true" --method GET
undefined

Delete Repository

删除镜像仓库

Warning: This deletes the repository and ALL its tags!
bash
undefined
警告: 此操作会删除整个镜像仓库及其所有标签！
bash
undefined

Delete entire repository

删除整个镜像仓库

glab api projects/123/registry/repositories/456 --method DELETE
undefined
glab api projects/123/registry/repositories/456 --method DELETE
undefined

List Tags in Repository

列出镜像仓库中的标签

bash
undefined
bash
undefined

List all tags

列出所有标签

glab api projects/123/registry/repositories/456/tags --method GET
glab api projects/123/registry/repositories/456/tags --method GET

With pagination

分页列出

glab api projects/123/registry/repositories/456/tags --paginate
undefined
glab api projects/123/registry/repositories/456/tags --paginate
undefined

Get Tag Details

获取标签详情

bash
undefined
bash
undefined

Get specific tag

获取指定标签详情

glab api projects/123/registry/repositories/456/tags/latest --method GET
glab api projects/123/registry/repositories/456/tags/latest --method GET

Get tag with digest info

获取包含摘要信息的标签

glab api projects/123/registry/repositories/456/tags/v1.0.0 --method GET
undefined
glab api projects/123/registry/repositories/456/tags/v1.0.0 --method GET
undefined

Delete Single Tag

删除单个标签

bash
undefined
bash
undefined

Delete specific tag

删除指定标签

glab api projects/123/registry/repositories/456/tags/v1.0.0 --method DELETE
glab api projects/123/registry/repositories/456/tags/v1.0.0 --method DELETE

Delete 'latest' tag

删除'latest'标签

glab api projects/123/registry/repositories/456/tags/latest --method DELETE
undefined
glab api projects/123/registry/repositories/456/tags/latest --method DELETE
undefined

Bulk Delete Tags

批量删除标签

bash
undefined
bash
undefined

Delete tags matching regex (keep none)

删除匹配正则的所有标签（不保留任何标签）

glab api projects/123/registry/repositories/456/tags --method DELETE
-f name_regex_delete=".*"
glab api projects/123/registry/repositories/456/tags --method DELETE
-f name_regex_delete=".*"

Delete all tags except last 5

删除所有标签，仅保留最新5个

glab api projects/123/registry/repositories/456/tags --method DELETE
-f name_regex_delete=".*"
-f keep_n=5
glab api projects/123/registry/repositories/456/tags --method DELETE
-f name_regex_delete=".*"
-f keep_n=5

Delete tags older than 30 days, keep last 10

删除30天前的标签，仅保留最新10个

glab api projects/123/registry/repositories/456/tags --method DELETE
-f name_regex_delete=".*"
-f keep_n=10
-f older_than="30d"
glab api projects/123/registry/repositories/456/tags --method DELETE
-f name_regex_delete=".*"
-f keep_n=10
-f older_than="30d"

Delete only dev/snapshot tags

仅删除开发/快照标签

glab api projects/123/registry/repositories/456/tags --method DELETE
-f name_regex_delete="^dev-.*"
glab api projects/123/registry/repositories/456/tags --method DELETE
-f name_regex_delete="^dev-.*"

Keep tags matching pattern (exclude from deletion)

保留匹配指定规则的标签（不删除这些标签）

glab api projects/123/registry/repositories/456/tags --method DELETE
-f name_regex_delete=".*"
-f name_regex_keep="^v[0-9]+\.[0-9]+\.[0-9]+$"
-f keep_n=5
undefined
glab api projects/123/registry/repositories/456/tags --method DELETE
-f name_regex_delete=".*"
-f name_regex_keep="^v[0-9]+\.[0-9]+\.[0-9]+$"
-f keep_n=5
undefined

Bulk Delete Options

批量删除选项

OptionTypeDescription
name_regex_delete
stringRegex pattern for tags to delete
name_regex_keep
stringRegex pattern for tags to keep (overrides delete)
keep_n
integerNumber of latest tags to keep
older_than
stringDelete tags older than duration (e.g., 
30d
, 
1w
)
选项类型说明
name_regex_delete
字符串要删除的标签匹配正则表达式
name_regex_keep
字符串要保留的标签匹配正则表达式（优先级高于删除规则）
keep_n
整数要保留的最新标签数量
older_than
字符串删除早于指定时长的标签（例如：
30d
表示30天，
1w
表示1周）

Common Workflows

常见工作流

Workflow 1: List All Images and Tags

工作流1：列出所有镜像及标签

bash
project_id=123
bash
project_id=123

Get all repositories

获取所有镜像仓库

repos=$(glab api projects/$project_id/registry/repositories --paginate)
repos=$(glab api projects/$project_id/registry/repositories --paginate)

For each repository, list tags

遍历每个镜像仓库，列出标签

echo "$repos" | jq -r '.[].id' | while read repo_id; do repo_name=$(echo "$repos" | jq -r ".[] | select(.id == $repo_id) | .path") echo "=== $repo_name ===" glab api projects/$project_id/registry/repositories/$repo_id/tags |
jq -r '.[].name' echo "" done
undefined
echo "$repos" | jq -r '.[].id' | while read repo_id; do repo_name=$(echo "$repos" | jq -r ".[] | select(.id == $repo_id) | .path") echo "=== $repo_name ===" glab api projects/$project_id/registry/repositories/$repo_id/tags |
jq -r '.[].name' echo "" done
undefined

Workflow 2: Find Large Images

工作流2：查找大体积镜像

bash
project_id=123
repo_id=456
bash
project_id=123
repo_id=456

List tags with sizes

列出包含大小信息的标签

glab api projects/$project_id/registry/repositories/$repo_id/tags --paginate |
jq -r 'sort_by(.total_size) | reverse | .[] | "(.name): (.total_size / 1024 / 1024 | floor) MB"'
undefined
glab api projects/$project_id/registry/repositories/$repo_id/tags --paginate |
jq -r 'sort_by(.total_size) | reverse | .[] | "(.name): (.total_size / 1024 / 1024 | floor) MB"'
undefined

Workflow 3: Clean Up Old Development Images

工作流3：清理旧开发镜像

bash
project_id=123
repo_id=456
bash
project_id=123
repo_id=456

Delete dev images older than 7 days, keep last 3

删除7天前的开发镜像，仅保留最新3个

glab api projects/$project_id/registry/repositories/$repo_id/tags --method DELETE
-f name_regex_delete="^dev-.*"
-f older_than="7d"
-f keep_n=3
undefined
glab api projects/$project_id/registry/repositories/$repo_id/tags --method DELETE
-f name_regex_delete="^dev-.*"
-f older_than="7d"
-f keep_n=3
undefined

Workflow 4: Keep Only Release Tags

工作流4：仅保留正式版本标签

bash
project_id=123
repo_id=456
bash
project_id=123
repo_id=456

Delete everything except semver tags, keep last 10

删除所有标签，仅保留语义化版本标签，且保留最新10个

glab api projects/$project_id/registry/repositories/$repo_id/tags --method DELETE
-f name_regex_delete=".*"
-f name_regex_keep="^v[0-9]+\.[0-9]+\.[0-9]+$"
-f keep_n=10
undefined
glab api projects/$project_id/registry/repositories/$repo_id/tags --method DELETE
-f name_regex_delete=".*"
-f name_regex_keep="^v[0-9]+\.[0-9]+\.[0-9]+$"
-f keep_n=10
undefined

Workflow 5: Audit Registry Usage

工作流5：审计镜像仓库使用情况

bash
project_id=123
bash
project_id=123

Get total size per repository

获取每个镜像仓库的总存储大小

glab api "projects/$project_id/registry/repositories?tags_count=true" --paginate |
jq -r '.[] | "(.path): (.tags_count) tags"'
glab api "projects/$project_id/registry/repositories?tags_count=true" --paginate |
jq -r '.[] | "(.path): (.tags_count) tags"'

Get detailed size info for a repository

获取指定镜像仓库的详细存储信息

repo_id=456 glab api projects/$project_id/registry/repositories/$repo_id/tags --paginate |
jq '[.[] | .total_size] | add / 1024 / 1024 | "Total: (. | floor) MB"'
undefined
repo_id=456 glab api projects/$project_id/registry/repositories/$repo_id/tags --paginate |
jq '[.[] | .total_size] | add / 1024 / 1024 | "Total: (. | floor) MB"'
undefined

Workflow 6: Find and Delete Untagged Images

工作流6：查找并删除无标签镜像

bash
project_id=123
repo_id=456
bash
project_id=123
repo_id=456

Note: Untagged images are automatically cleaned up by GitLab

注意：无标签镜像会被GitLab自动清理

You can trigger cleanup by deleting all tags and then the repo

可以通过删除所有标签后再删除仓库来触发清理

Or wait for the scheduled cleanup job

或者等待定时清理任务执行

undefined
undefined

Workflow 7: Export Tag List for Backup

工作流7：导出标签列表用于备份

bash
project_id=123
repo_id=456
bash
project_id=123
repo_id=456

Export tag names

导出标签名称

glab api projects/$project_id/registry/repositories/$repo_id/tags --paginate |
jq -r '.[].name' > tags_backup.txt
glab api projects/$project_id/registry/repositories/$repo_id/tags --paginate |
jq -r '.[].name' > tags_backup.txt

Export with details

导出包含详细信息的标签

glab api projects/$project_id/registry/repositories/$repo_id/tags --paginate |
jq -r '.[] | [.name, .created_at, .total_size] | @csv' > tags_details.csv
undefined
glab api projects/$project_id/registry/repositories/$repo_id/tags --paginate |
jq -r '.[] | [.name, .created_at, .total_size] | @csv' > tags_details.csv
undefined

Registry URL Format

镜像仓库URL格式

GitLab Container Registry URLs follow this pattern:
registry.gitlab.com/<namespace>/<project>
registry.gitlab.com/<namespace>/<project>/<image>
For example:
  • registry.gitlab.com/mygroup/myproject
  • registry.gitlab.com/mygroup/myproject/app
  • registry.gitlab.com/mygroup/myproject/api
GitLab容器镜像仓库URL遵循以下格式：
registry.gitlab.com/<namespace>/<project>
registry.gitlab.com/<namespace>/<project>/<image>
示例：
  • registry.gitlab.com/mygroup/myproject
  • registry.gitlab.com/mygroup/myproject/app
  • registry.gitlab.com/mygroup/myproject/api

Troubleshooting

故障排查

IssueCauseSolution
403 ForbiddenNo registry accessCheck token scopes, need 
read_registry
404 Not FoundRegistry disabled or repo doesn't existEnable registry in project settings
Delete failsInsufficient permissionsNeed Developer+ role or 
write_registry
scope
Bulk delete no effectNo matching tagsCheck regex pattern
Old images persistGitLab cleanup jobWait for scheduled cleanup or delete manually
问题原因解决方法
403 Forbidden（禁止访问）无镜像仓库访问权限检查令牌权限范围，需要
read_registry
权限
404 Not Found（未找到）镜像仓库未启用或仓库不存在在项目设置中启用镜像仓库
删除操作失败权限不足需要Developer及以上角色或
write_registry
权限范围
批量删除无效果无匹配标签检查正则表达式规则
旧镜像仍然存在GitLab清理任务未执行等待定时清理任务执行或手动删除

Size Limits and Quotas

存储限制与配额

  • GitLab.com has storage quotas per namespace
  • Self-managed instances may have different limits
  • Check namespace storage usage in Settings > Usage Quotas
  • GitLab.com每个命名空间有存储配额
  • 自托管实例可能有不同的限制
  • 在设置 > 使用配额中查看命名空间存储使用情况

Best Practices

最佳实践

  1. Regular cleanup: Set up scheduled cleanup with 
    older_than
    and 
    keep_n
  2. Tag strategy: Use meaningful tags (semver, commit SHA, branch name)
  3. Keep release tags: Use 
    name_regex_keep
    to preserve important versions
  4. Monitor storage: Check registry size regularly
  5. Use CI cleanup: Add cleanup job to CI pipeline
  1. 定期清理：使用
    older_than
    和
    keep_n
    设置定时清理任务
  2. 标签策略：使用有意义的标签（语义化版本、提交SHA、分支名称）
  3. 保留正式版本标签：使用
    name_regex_keep
    保留重要版本
  4. 监控存储：定期检查镜像仓库大小
  5. 使用CI清理：在CI流水线中添加清理任务

Related Documentation

相关文档