azy5030-overlay/CLAUDE.md

CLAUDE.md

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

What this is

A personal Gentoo ebuild repository (overlay), repo name azy5030, EAPI 8, masters = gentoo, thin + unsigned Manifests (metadata/layout.conf). It packages software not in the main ::gentoo tree. Currently one package: dev-util/gitea-runner. Hosted on a self-hosted Gitea at git.azy.dev whose repos use SHA-256 object format.

The vendored-build model (the core design)

dev-util/gitea-runner is a go-module ebuild built offline from upstream gitea/runner source. Gentoo's build sandbox has no network, so Go modules cannot be fetched at build time. Instead they are vendored ahead of time:

1. The upstream source archive is SRC_URI'd from gitea.com's /api/v1/.../archive endpoint (a plain git clone/go get is never used).
2. A vendor tarball (${P}-vendor.tar.xz, the result of go mod vendor, packed deterministically) is uploaded as a release asset on this repo and is the second SRC_URI. S="${WORKDIR}/runner".
3. dev-util/gitea-runner/Manifest pins BLAKE2B/SHA512 of both tarballs. emerge verifies against the Manifest, then compiles offline from vendor/.

Consequences when editing the ebuild:

• LICENSE must cover every vendored module's license, not just upstream's MIT. The bump PR checklist suggests go-licenses report ./... to confirm.
• BDEPEND Go version tracks upstream's go.mod go directive.
• The version string is injected via ldflags into gitea.com/gitea/runner/internal/pkg/ver.version; CI asserts gitea-runner --version echoes v${PV}. If upstream moves that symbol path, the build "succeeds" but reports the wrong version.

Bumping to a new upstream version

This is automated by scripts/bump-version.sh (run daily by bump.yaml, or workflow_dispatch). To do it manually you must reproduce its steps, because a version bump is never just renaming the ebuild — the vendor tarball must be regenerated and re-uploaded as a release asset, or the build will fail Manifest verification. The script:

1. Reads the latest vX.Y.Z from upstream releases.rss; compares to the newest committed ebuild. Exits early if up to date or if a bump/gitea-runner-<ver> branch already exists.
2. Downloads the source archive, runs go mod vendor, packs a reproducible *-vendor.tar.xz (--sort=name --mtime='UTC 1970-01-01' --owner=0 --group=0).
3. Creates/reuses a release tagged ${PN}-${ver}-vendor and uploads the tarball asset.
4. git mvs the ebuild to the new version, rewrites BDEPEND's Go version from upstream go.mod, and regenerates the Manifest with pkgdev manifest (after copying both distfiles into /var/cache/distfiles and wiring a temporary repos.conf).
5. Validates: pkgcheck scan, then emerge + gitea-runner --version | grep v${ver}.
6. Commits, pushes the branch, opens a PR against master.

Requires a BUMP_TOKEN repo secret (scopes: repository read/write, write release) plus a Gentoo env with go pkgdev git curl xz jq.

CI (.gitea/workflows/ci.yaml)

Runs on every push inside a gentoo/stage3:amd64-openrc container (the runs-on label only schedules onto the Docker-backend runner). Steps: emerge-webrsync to sync ::gentoo → configure portage (disables binpkg signature verification so prebuilt deps like dev-lang/go are pulled, not compiled) → check out via curl + tar, not actions/checkout (it breaks on SHA-256 Gitea repos) into /var/db/repos/azy5030 → pkgcheck scan → emerge → assert gitea-runner --version matches the ebuild version.

Conventions / gotchas

• YAML is linted by .yamllint.yaml (relaxed: line-length and document-start disabled; truthy.check-keys: false so on: is allowed unquoted).
• metadata/md5-cache/ is gitignored — portage regenerates it on sync, so never commit it (a stale gitea-runner-1.0.4 file may linger on disk untracked).
• The bump script and CI deliberately preserve the scheme of GITHUB_SERVER_URL: on the self-hosted runner it is an internal http:// endpoint. Don't hardcode https.
• New packages must be added to profiles/categories (currently just dev-util).