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. (This repo is a standard SHA-1 repo; the sibling homeserver repo is SHA-256, so workflow snippets copied from it may carry a GIT_DEFAULT_HASH: sha256 checkout override that this repo must not use.)

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. Commits, pushes the branch, opens a PR against master. The script does not emerge or pkgcheck the result itself: the branch push triggers CI, which does both (and fetches the real release asset, which the script's local copy never would).

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, two jobs. A lint job runs on the plain Docker-backend runner (no container), checks out with actions/checkout, installs the linters, and runs just lint (markdownlint/shellcheck/yamllint/actionlint). The build job has needs: lint (lint is a gate) and runs inside a gentoo/stage3:amd64-openrc container: 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 into /var/db/repos/azy5030 → pkgcheck scan → emerge → assert gitea-runner --version matches the ebuild version.

The build job can't use actions/checkout (even though the lint job does): the Gitea runner executes JS actions by docker exec node … inside the job container, and gentoo/stage3 ships no node, so any JS action fails with exit 127. The lint job has no container:, so it runs in the runner's default node-capable image and checkout works.

Vendor-tag repointing (.gitea/workflows/vendor-tags.yaml)

The bump script creates the ${PN}-${ver}-vendor release before the bump commit exists, so its tag points at whatever master was at the time (and squash/rebase merges mean the branch commit never lands on master anyway). On every push to master touching dev-util/**, this workflow force-updates each vendor tag whose ebuild is still in the tree to the master commit that added that ebuild. It only ever updates tags: deleting a release's tag makes Gitea delete the release and its assets, breaking the ebuild's SRC_URI. Tag pushes don't re-trigger CI because ci.yaml is filtered to branch pushes.

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).