glab-tools

A collection of CLI tools for GitLab CI/CD pipelines.

Installation

Using Docker (Recommended for CI/CD)

# In your .gitlab-ci.yml
cleanup-registry:
  image:
    name: registry.gitlab.com/your-group/gitlab-tools:latest
    entrypoint: [""]
  script:
    - glab-tools registry cleanup --keep 3

Building from source

go build -o glab-tools .

Commands

registry cleanup

Clean up old container registry tags for the current branch.

This command retrieves all container tags prefixed with the current branch name and deletes all but the most recent ones (based on creation time). If running on the default branch, the command does nothing.

Usage:

glab-tools registry cleanup [flags]

Flags:

Flag	Short	Default	Description
--keep	-k	3	Number of recent tag groups to keep
--dry-run	-n	false	Show what would be deleted without actually deleting
--repository	-r	""	Repository name within the project (defaults to all repositories)
--image		""	Full registry image path to target (env: CI_REGISTRY_IMAGE)
--related-tags		""	Comma-separated suffixes for related tags to delete together
--project-id		""	GitLab project ID (env: CI_PROJECT_ID)
--branch		""	Current branch name (env: CI_COMMIT_REF_NAME)
--default-branch		""	Default branch name (env: CI_DEFAULT_BRANCH)
--api-url		""	GitLab API URL (env: CI_API_V4_URL)
--token		""	GitLab token (env: CI_JOB_TOKEN or GITLAB_TOKEN)
--job-token		false	Use JOB-TOKEN header instead of PRIVATE-TOKEN

All parameters can be set via CLI flags or environment variables. CLI flags take precedence. When running in GitLab CI/CD, the environment variables are set automatically.

Authentication:

The tool supports two authentication methods:

• CI_JOB_TOKEN / --token with --job-token - Uses JOB-TOKEN header (preferred in CI, auto-detected from env)
• GITLAB_TOKEN / --token - Uses PRIVATE-TOKEN header (fallback)

Handling Multi-Architecture Images:

When using multi-arch manifests with architecture-specific tags, use --related-tags to ensure all related images are deleted together:

# Tags: feature-abc123, feature-abc123-amd64, feature-abc123-arm64
glab-tools registry cleanup --keep 3 --related-tags="-amd64,-arm64"

This groups tags by their "main" tag (without suffixes) and deletes entire groups together, preventing orphaned architecture-specific images.

Targeting Sub-Image Repositories:

GitLab projects can have multiple container registry repositories. For example, a project might publish both a root image and sub-images:

registry.example.com/group/project            # root repository
registry.example.com/group/project/subimage    # sub-image repository

Use the --image flag (or CI_REGISTRY_IMAGE env var) to target a specific repository by its full image path:

# Clean up tags in a sub-image repository
glab-tools registry cleanup --image registry.example.com/group/project/subimage

# Or target the root repository explicitly
glab-tools registry cleanup --image registry.example.com/group/project

Alternatively, use --repository to match by repository name directly:

glab-tools registry cleanup --repository subimage

Example CI/CD Usage:

Single-architecture images:

cleanup-registry:
  stage: cleanup
  image:
    name: registry.gitlab.com/your-group/gitlab-tools:latest
    entrypoint: [""]
  script:
    - glab-tools registry cleanup --keep 3
  rules:
    - if: $CI_COMMIT_BRANCH && $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH

Multi-architecture images:

cleanup-registry:
  stage: cleanup
  image:
    name: registry.gitlab.com/your-group/gitlab-tools:latest
    entrypoint: [""]
  script:
    - glab-tools registry cleanup --keep 3 --related-tags="-amd64,-arm64"
  rules:
    - if: $CI_COMMIT_BRANCH && $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH

Releases

Docker images are built and pushed:

• On semver tags (e.g., v1.0.0, 1.2.3): Tagged with version and latest
• On non-default branches: Tagged with {branch}-{short-sha} for testing

The CI/CD pipeline:

1. Builds Go binaries for both architectures (amd64 and arm64) on every commit
2. On non-default branches: Creates and pushes Docker images for testing
3. On non-default branches: Runs registry cleanup to remove old branch images
4. On semver tags: Creates Docker images tagged with version and latest

The arm64 builds run on runners tagged with docker-arm64.

To create a release:

git tag v1.0.0
git push origin v1.0.0

Project Structure

.
├── cmd/
│   ├── root.go              # Root command
│   └── registry/
│       ├── registry.go      # Registry parent command
│       └── cleanup.go       # Cleanup subcommand
├── internal/
│   └── gitlab/
│       └── registry.go      # GitLab API client
├── main.go
├── Dockerfile
├── .gitlab-ci.yml
└── README.md

Contributing

1. Create a feature branch
2. Make your changes
3. Submit a merge request

License

MIT