Merge pull request 'docs: add CLAUDE.md for Claude Code guidance' (#355) from add-claude-md into main

Reviewed-on: #355

.gitea/workflows/ci.yaml

@@ -0,0 +1,42 @@
+name: gitlab-cleanup-handler
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version: 'stable'
+      - name: Run tests
+        run: go test -race -coverprofile=coverage.txt ./...
+
+  vulnerabilities:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version: 'stable'
+      - name: Check vulnerabilities
+        run: |
+          go install golang.org/x/vuln/cmd/govulncheck@latest
+          govulncheck ./...
+
+  build:
+    needs: [test, vulnerabilities]
+    runs-on: ubuntu-latest
+    env:
+      BUILDTOOLS_CONTENT: ${{ secrets.BUILDTOOLS_CONTENT }}
+      GITEA_REPOSITORY: ${{ gitea.repository }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: buildtool/setup-buildtools-action@v1
+      - name: Build and push
+        run: unset GITEA_TOKEN && build && push

.gitea/workflows/release.yaml

@@ -0,0 +1,9 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    uses: unboundsoftware/shared-workflows/.gitea/workflows/Release.yml@main

.pre-commit-config.yaml

@@ -36,6 +36,6 @@ repos:
   - id: go-vet
   - id: gofumpt
 - repo: https://github.com/golangci/golangci-lint
-  rev: v2.7.2
+  rev: v2.8.0
   hooks:
   - id: golangci-lint

CLAUDE.md

@@ -0,0 +1,52 @@
+# 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
+
+```bash
+# 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)

Dockerfile

@@ -1,4 +1,4 @@
-FROM amd64/golang:1.25.5@sha256:0c27bcf0df81eca89f87e1e78be5ad5e36487f0eaf71cd900ba14ee7621d3e70 as build
+FROM amd64/golang:1.25.5@sha256:ad03ba93327b8a6143b49373790b5d92c28067bdb814418509466122ee9c9e63 as build
 WORKDIR /build
 ENV CGO_ENABLED=0
 ADD . /build