gitlab-cleanup-handler/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A Go service that scans Kubernetes namespaces for container images from GitLab's container registry and automatically updates GitLab project cleanup policies to preserve those images. This ensures images actively running in Kubernetes are protected from automated cleanup.

Build & Test Commands

# Run all tests
go test ./...

# Run a specific test
go test ./kube -run TestFetcher

# Run tests with coverage
go test -cover ./...

# Lint (via pre-commit)
pre-commit run golangci-lint --all-files

# Format code
gofumpt -w .

# Run all pre-commit hooks (always add all files first)
git add -A && pre-commit run --all-files

Architecture

The service has three main components:

1. cmd/handler - Entry point using Kong for CLI argument parsing. Accepts --namespaces (or NAMESPACES env) and --gitlab-token (or GITLAB_TOKEN env).

2. kube - Kubernetes client that scans Deployments and CronJobs in specified namespaces for images prefixed with registry.gitlab.com. Uses provider pattern for in-cluster vs KUBECONFIG-based authentication.

3. gitlab - REST client that fetches repository tags and updates container expiration policies via GitLab API. The cleanup policy keeps images matching main|master|<active-versions>.

Data Flow

Kubernetes Cluster → kube.Client.GetImages() → ImageCollector
    → gitlab.RestClient.GetTags() + UpdateCleanupPolicy()

Code Conventions

• Uses github.com/apex/log for structured JSON logging
• Tests use github.com/stretchr/testify assertions and gitlab.com/unboundsoftware/apex-mocks for log mocking
• Interfaces defined locally for testability (KubeClient, GitlabClient, ClientProvider, ConfigProvider)
• Follows conventional commits format (enforced by pre-commit commitlint hook)