ci(bump): gate toolchain install behind a cheap version check; fix binpkg verify (#4)

## Why

The daily **Bump** job (`runs/107` and every other scheduled run) does ~5–26 min
of work on every run before it ever checks whether a bump is needed — and on the
common no-op day it isn't. Timeline of a no-op run:

`docker pull stage3` → `emerge-webrsync` → **`emerge … dev-lang/go dev-util/pkgdev` (29 pkgs)** → `bump-version.sh` finds `already at latest` and exits in **1 second**.

`go`/`pkgdev`/`xz`/`jq` are only needed when a bump actually happens. Recent
no-op scheduled runs took 5m, 26m, 9m, 5m, 10m — all to do nothing.

Separately, the log on every emerge was flooded with binpkg GPG failures
(`unknown key`, `pubring.kbx: No such file`, `Try running getuto`). The
`sed 's/^verify-signature = true/.../'` matched nothing in the stage3 binhost
config, so the intended "disable binpkg signature verification" never took
effect (it worked anyway only because the failures are non-fatal).

## What

- **`bump.yaml`**: add a cheap `Check whether a bump is needed` step that compares
  the newest upstream release (`releases.rss`) against the newest committed ebuild
  (Gitea contents API) using only base-image `wget`, and gate `Sync ::gentoo`,
  the toolchain install, and the bump step on its `needed` output. The gate only
  short-circuits when **confident** (both versions parsed and current ≥ upstream);
  on any doubt — failed fetch, unparseable version — it falls through to the full
  run, where `bump-version.sh` remains the source of truth and re-checks.
- **`bump.yaml` + `ci.yaml`**: replace the no-op `sed` with `sed -i '/^verify-signature/d'`
  + append `verify-signature = false`, so the knob is actually set regardless of
  the stage3 default contents.

## Notes / limits

- The job `container:` still pulls `gentoo/stage3` before the gate runs, so the
  ~3.5 min image pull on no-op days is unchanged; this saves the larger
  webrsync + 29-package emerge. A follow-up could split the gate into a separate
  container-less job to skip the pull too, but that depends on what the runner
  maps `runs-on: ubuntu-latest` to, so it's left out here.
- Validated: `yamllint -c .yamllint.yaml` clean on both files; version-comparison
  logic and the contents-API JSON parsing unit-tested locally (equal / upstream-newer /
  current-ahead / parse-failure cases).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: #4
Co-authored-by: Ali Zein Yousuf <azy5030@gmail.com>
Co-committed-by: Ali Zein Yousuf <azy5030@gmail.com>

CLAUDE.md

@@ -0,0 +1,85 @@
+# 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 mv`s 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, 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.
+
+## 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`).