gitlab-container

Container Registry Skill

Container registry management for GitLab using glab api raw endpoint calls.

Quick Reference

Operation	Command Pattern	Risk
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

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)

API Prerequisites

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.

Available Commands

List Container Repositories

# 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 Repository Details

# 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 Repository

Warning: This deletes the repository and ALL its tags!

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

List Tags in Repository

# 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 Tag Details

# 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 Single Tag

# 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

Bulk Delete Tags

# 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

Bulk Delete Options

Option	Type	Description
name_regex_delete	string	Regex pattern for tags to delete
name_regex_keep	string	Regex pattern for tags to keep (overrides delete)
keep_n	integer	Number of latest tags to keep
older_than	string	Delete tags older than duration (e.g., 30d, 1w)

Common Workflows

Workflow 1: List All Images and Tags

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

Workflow 2: Find Large Images

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

Workflow 3: Clean Up Old Development Images

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

Workflow 4: Keep Only Release Tags

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

Workflow 5: Audit Registry Usage

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

Workflow 6: Find and Delete Untagged Images

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

Workflow 7: Export Tag List for Backup

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

Registry URL Format

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

Troubleshooting

Issue	Cause	Solution
403 Forbidden	No registry access	Check token scopes, need read_registry
404 Not Found	Registry disabled or repo doesn't exist	Enable registry in project settings
Delete fails	Insufficient permissions	Need Developer+ role or write_registry scope
Bulk delete no effect	No matching tags	Check regex pattern
Old images persist	GitLab cleanup job	Wait for scheduled cleanup or delete manually

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

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

Related Documentation

• API Helpers
• Safeguards
• Quick Reference
• GitLab Container Registry API