gitlab-container

容器注册表技能

使用 glab api 原始端点调用管理 GitLab 容器注册表。

快速参考

操作	命令模式	风险
列出仓库	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 ...	⚠️⚠️⚠️

风险说明：- 安全 | ⚠️ 谨慎 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

何时使用此技能

始终在以下情况使用：

• 用户提到“容器”“注册表”“Docker 镜像”或“容器镜像”
• 用户想列出或删除 Docker 标签
• 用户提到“镜像清理”或“注册表清理”
• 用户想查看容器仓库信息

以下情况绝不要使用：

• 用户想构建或推送 Docker 镜像（使用 CI/CD 或 Docker 命令行）
• 用户想运行容器（使用 Docker 命令行或编排工具）
• 用户想使用软件包注册表（使用不同的 API）

API 前提条件

所需令牌作用域： read_registry、write_registry（用于删除操作）或 api

权限：

• 读取注册表：Reporter+
• 删除镜像：Developer+（或根据设置使用 Maintainer）

注意： 项目必须启用 Container Registry。

可用命令

列出容器仓库

# List all repositories in project
glab api projects/123/registry/repositories --method GET

# With pagination
glab api projects/123/registry/repositories --paginate

# Include tags count
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"

获取仓库详情

# Get specific repository
glab api projects/123/registry/repositories/456 --method GET

# With tags count
glab api "projects/123/registry/repositories/456?tags_count=true" --method GET

删除仓库

警告： 这会删除该仓库及其所有标签！

# Delete entire repository
glab api projects/123/registry/repositories/456 --method DELETE

列出仓库中的标签

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

# With pagination
glab api projects/123/registry/repositories/456/tags --paginate

获取标签详情

# Get specific tag
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

删除单个标签

# Delete specific tag
glab api projects/123/registry/repositories/456/tags/v1.0.0 --method DELETE

# Delete 'latest' tag
glab api projects/123/registry/repositories/456/tags/latest --method DELETE

批量删除标签

# Delete tags matching regex (keep none)
glab api projects/123/registry/repositories/456/tags --method DELETE \
  -f name_regex_delete=".*"

# Delete all tags except last 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
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-.*"

# 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

批量删除选项

选项	类型	说明
name_regex_delete	string	要删除的标签的正则表达式模式
name_regex_keep	string	要保留的标签的正则表达式模式（优先于删除规则）
keep_n	integer	要保留的最新标签数量
older_than	string	删除早于指定时长的标签（例如 30d、1w）

常见工作流

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

project_id=123

# Get all repositories
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

工作流 2：查找大型镜像

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

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

project_id=123
repo_id=456

# Delete dev images older than 7 days, keep last 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

工作流 4：仅保留发布标签

project_id=123
repo_id=456

# Delete everything except semver tags, keep last 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

工作流 5：审计注册表用量

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

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

工作流 6：查找并删除未标记的镜像

project_id=123
repo_id=456

# Note: Untagged images are automatically cleaned up by GitLab
# You can trigger cleanup by deleting all tags and then the repo
# Or wait for the scheduled cleanup job

工作流 7：导出标签列表以供备份

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

# 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

注册表 URL 格式

GitLab Container Registry 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

故障排除

问题	原因	解决方案
403 Forbidden	无权访问注册表	检查令牌作用域，需要 read_registry
404 Not Found	注册表已禁用或仓库不存在	在项目设置中启用注册表
删除失败	权限不足	需要 Developer+ 角色或 write_registry 作用域
批量删除无效	没有匹配的标签	检查正则表达式模式
旧镜像仍存在	GitLab 清理任务	等待计划的清理任务运行，或手动删除

大小限制和配额

• GitLab.com 按命名空间设置存储配额
• 自托管实例可能有不同的限制
• 在 Settings > Usage Quotas 中查看命名空间的存储用量

最佳实践

1. 定期清理：使用 older_than 和 keep_n 设置定期清理
2. 标签策略：使用有意义的标签（semver、提交 SHA、分支名称）
3. 保留发布标签：使用 name_regex_keep 保留重要版本
4. 监控存储：定期检查注册表大小
5. 使用 CI 清理：在 CI 流水线中添加清理任务

相关文档

• API 辅助工具
• 安全防护措施
• 快速参考
• GitLab Container Registry API