gitlab-container

Container Registry スキル

glab api の raw エンドポイント呼び出しを使用した 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 image」、「コンテナイメージ」について言及した場合
• ユーザーが Docker タグの一覧表示または削除を希望する場合
• ユーザーが「イメージのクリーンアップ」、「レジストリのクリーンアップ」について言及した場合
• ユーザーがコンテナリポジトリの情報を確認したい場合

使用しないでください：

• ユーザーが Docker イメージのビルドまたはプッシュを希望する場合（CI/CD または docker CLI を使用してください）
• ユーザーがコンテナの実行を希望する場合（docker CLI またはオーケストレーターを使用してください）
• ユーザーがパッケージレジストリを希望する場合（別の 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