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 ```bash # 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 ```bash # 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! ```bash # Delete entire repository glab api projects/123/registry/repositories/456 --method DELETE ``` ### List Tags in Repository ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash 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 ```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"' ``` ### Workflow 3: Clean Up Old Development Images ```bash 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 ```bash 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 ```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"' # 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 ```bash 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 ```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 # 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](../shared/docs/API_HELPERS.md) - [Safeguards](../shared/docs/SAFEGUARDS.md) - [Quick Reference](../shared/docs/QUICK_REFERENCE.md) - [GitLab Container Registry API](https://docs.gitlab.com/ee/api/container_registry.html)