ci-image/CLAUDE.md

CLAUDE.md

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

What this repo is

A single-purpose repository that builds a CI base image: eclipse-temurin:17 (Java 17) extended with Node.js and the Docker CLI/daemon (via get.docker.com). The resulting image is meant to be used as a build/runner environment that needs Java, Node, and Docker-in-Docker available together.

There is no application code, no test suite, and no build tooling — the entire deliverable is the Dockerfile. "Building" means building the Docker image; "shipping" means pushing it to the Gitea container registry.

Commands

# Build locally (mirror what CI does)
docker build -t gitea.tail276105.ts.net/boxi/ci-image:local .

CI builds and pushes automatically — see below. There is nothing to lint or test.

CI/CD — Gitea Actions

.gitea/workflows/docker.yml runs on every push to main and: logs in to the registry → builds the image → tags it as both ${GITHUB_RUN_NUMBER} and latest → pushes both → logs out.

Target registry: gitea.tail276105.ts.net, image path boxi/ci-image (derived from ${{ gitea.repository }}, lowercased).

Registry auth — important gotchas

The push step is the fragile part. Login can succeed while the push fails with 401 Unauthorized on blobs/uploads. That is not a workflow bug — it means the credentials authenticate but lack write access to the boxi package namespace. Requirements:

• REGISTRY_USER must be the namespace owner (boxi) or a user with write access to that namespace — a separate service user cannot push to boxi/....
• REGISTRY_PASSWORD should be a Gitea access token with write:package scope (Gitea → Settings → Applications → Manage Access Tokens). The plain account password fails when 2FA is enabled.

Package ↔ repository linking

A pushed package shows up under the user namespace, not automatically under the repository's Packages tab. Auto-linking via the org.opencontainers.image.source label in the Dockerfile is unreliable here because BuildKit produces a multi-arch manifest list with an attestation manifest, which Gitea's label-based linking does not reliably read. Link the package to the repo manually once in the Gitea UI (Package → Package Settings → Repository); the link then persists across future pushes.

Conventions

• Commits & pushes are done by the maintainer manually — do not commit or push unless explicitly asked.
• Node 16 in the Dockerfile is EOL; bumping the setup_NN.x version is a known pending improvement but is intentionally left untouched to keep scope small.