dev-util/gitea-runner: bump to 3.4.1

- ci.yaml: filter the push trigger to branches. An unfiltered `push` also
  fired for every tag ref, including the vendor-release tags the bump script
  creates via the API.
- bump-version.sh: remove the pkgcheck/emerge/--version validation before
  push. The branch push triggers CI, which runs the same checks and, unlike
  the script's local copy, fetches the real release asset. The PR body now
  asks for green CI instead of claiming the build passed in the bump job.
- vendor-tags.yaml: new workflow on pushes to master touching dev-util/**.
  The vendor release is created before the bump commit exists (and PRs are
  squash-merged), so its tag pointed at an arbitrary master commit. This
  force-updates each vendor tag whose ebuild is in the tree to the master
  commit that added that ebuild. Tags are only ever updated, never deleted,
  since deleting a release's tag deletes the release and its assets.
- CLAUDE.md: document both changes.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

.gitea/workflows/bump.yaml

@@ -2,7 +2,14 @@ name: Bump
 on:
   schedule:
     - cron: '0 5 * * *'
-  workflow_dispatch: {}
+  workflow_dispatch:
+    inputs:
+      version:
+        description: >-
+          Upstream gitea/runner version to bump to (e.g. 3.4.0, no leading
+          "v"). Leave empty to use the latest upstream release.
+        required: false
+        type: string
 
 jobs:
   bump:
@@ -10,23 +17,69 @@ jobs:
     container:
       image: gentoo/stage3:amd64-openrc
     steps:
+      # Cheap gate: compare the newest upstream release against the newest
+      # committed ebuild using only base-image tools (wget). The expensive
+      # toolchain install + bump below is skipped on the common no-op day, so a
+      # daily run that has nothing to do finishes in seconds instead of minutes.
+      # bump-version.sh re-checks this itself and remains the source of truth.
+      - name: Check whether a bump is needed
+        id: check
+        env:
+          BUMP_TOKEN: ${{ secrets.BUMP_TOKEN }}
+          BUMP_VERSION: ${{ inputs.version }}
+        run: |
+          # An explicitly requested version always runs the full bump.
+          if [ -n "${BUMP_VERSION}" ]; then
+            echo "needed=true" >> "$GITHUB_OUTPUT"
+            echo "explicit version requested: ${BUMP_VERSION}"
+            exit 0
+          fi
+          latest=$(wget -qO- https://gitea.com/gitea/runner/releases.rss \
+            | grep -oE '<title>v[0-9]+\.[0-9]+\.[0-9]+</title>' \
+            | head -1 | sed -E 's#</?title>##g; s/^v//')
+          current=$(wget -qO- --header="Authorization: token ${BUMP_TOKEN}" \
+            "${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}/contents/dev-util/gitea-runner" \
+            | grep -oE '"name": *"gitea-runner-[0-9.]+\.ebuild"' \
+            | sed -E 's#.*gitea-runner-([0-9.]+)\.ebuild.*#\1#' | sort -V | tail -1)
+          echo "upstream=${latest} current=${current}"
+          # Only short-circuit when we are CONFIDENT there is nothing to do
+          # (both versions parsed and current is >= upstream). On any doubt
+          # fall through to the full run and let bump-version.sh decide.
+          if [ -n "$latest" ] && [ -n "$current" ] \
+             && [ "$(printf '%s\n%s\n' "$current" "$latest" | sort -V | tail -1)" = "$current" ]; then
+            echo "needed=false" >> "$GITHUB_OUTPUT"
+            echo "nothing to do (upstream ${latest}, have ${current})"
+          else
+            echo "needed=true" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Sync ::gentoo
+        if: steps.check.outputs.needed == 'true'
         run: emerge-webrsync
 
       - name: Configure portage + install tooling
+        if: steps.check.outputs.needed == 'true'
         run: |
           mkdir -p /etc/portage/repos.conf
           printf '[DEFAULT]\nmain-repo = gentoo\n\n[gentoo]\nlocation = /var/db/repos/gentoo\n' \
             > /etc/portage/repos.conf/gentoo.conf
-          sed -i 's/^verify-signature = true/verify-signature = false/' \
+          sed -i '/^verify-signature/d' /etc/portage/binrepos.conf/gentoo.conf
-            /etc/portage/binrepos.conf/gentoo.conf
+          printf '\nverify-signature = false\n' >> /etc/portage/binrepos.conf/gentoo.conf
+          # Upstream's go.mod can require a Go that Gentoo only has under
+          # ~amd64 (GOTOOLCHAIN=local forbids auto-download), so accept the
+          # testing-keyworded dev-lang/go. It is built from source when no
+          # stable binpkg satisfies the requirement.
+          mkdir -p /etc/portage/package.accept_keywords
+          echo 'dev-lang/go ~amd64' > /etc/portage/package.accept_keywords/go
           emerge -q --getbinpkg \
             dev-vcs/git net-misc/curl app-arch/xz-utils app-misc/jq \
             dev-lang/go dev-util/pkgdev
 
       - name: Check for new release and open PR
+        if: steps.check.outputs.needed == 'true'
         env:
           BUMP_TOKEN: ${{ secrets.BUMP_TOKEN }}
+          BUMP_VERSION: ${{ inputs.version }}
         run: |
           host=${GITHUB_SERVER_URL#http://}; host=${host#https://}
           curl -fsSL "http://x-access-token:${BUMP_TOKEN}@${host}/${GITHUB_REPOSITORY}/raw/branch/master/scripts/bump-version.sh" \

.gitea/workflows/ci.yaml

@@ -1,8 +1,49 @@
 name: CI
-on: [push]
+# Restrict to branch pushes: an unfiltered `push` also fires for tag refs,
+# including the vendor-release tags the bump script creates via the API.
+on:
+  push:
+    branches:
+      - '**'
 
 jobs:
+  # Lint gate: runs on the plain Docker-backend runner (not the Gentoo
+  # container) and must pass before the build job starts. Mirrors the lint job
+  # in the homeserver repo; `just lint` runs markdownlint/shellcheck/yamllint/
+  # actionlint over the repo.
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # setup-just fetches its binary from GitHub; on a Gitea runner the default
+      # github-token is the *Gitea* token (GitHub rejects it 401), so pass none
+      # and use GitHub's unauthenticated API.
+      - uses: extractions/setup-just@v4
+        with:
+          github-token: ""
+
+      - uses: taiki-e/install-action@v2
+        env:
+          GITHUB_TOKEN: ""
+        with:
+          tool: shellcheck
+
+      - name: Install markdownlint-cli
+        run: npm install -g markdownlint-cli
+
+      # actionlint has no maintained setup-action and uv ships via astral.sh;
+      # both installers hit their own release assets (no GitHub token needed).
+      - name: Install yamllint + actionlint tooling
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin sh
+          bash <(curl -fsSL https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash) latest /usr/local/bin
+
+      - name: Run linters
+        run: just lint
+
   build:
+    needs: lint
     # The label only schedules the job on the (Docker-backend) runner; the steps
     # actually run inside the Gentoo container declared below.
     runs-on: ubuntu-latest
@@ -22,12 +63,16 @@ jobs:
           mkdir -p /etc/portage/repos.conf
           printf '[DEFAULT]\nmain-repo = gentoo\n\n[gentoo]\nlocation = /var/db/repos/gentoo\n' \
             > /etc/portage/repos.conf/gentoo.conf
-          sed -i 's/^verify-signature = true/verify-signature = false/' \
+          sed -i '/^verify-signature/d' /etc/portage/binrepos.conf/gentoo.conf
-            /etc/portage/binrepos.conf/gentoo.conf
+          printf '\nverify-signature = false\n' >> /etc/portage/binrepos.conf/gentoo.conf
           emerge -q --getbinpkg net-misc/curl dev-util/pkgcheck
 
-      # Place this overlay at /var/db/repos/azy5030. actions/checkout is avoided
+      # Place this overlay at /var/db/repos/azy5030 via curl + tar. actions/checkout
-      # (SHA-256 Gitea repos break it); curl + tar fetches the source archive.
+      # can't run here: this job uses the gentoo/stage3 container, and the Gitea
+      # runner executes JS actions with `node` *inside* that container
+      # (`docker exec node …`) — stage3 ships no node, so checkout fails with
+      # exit 127. (The lint job uses actions/checkout fine: it has no container:
+      # and runs in the runner's default node-capable image.)
       - name: Check out overlay
         env:
           TOKEN: ${{ github.token }}
@@ -41,6 +86,11 @@ jobs:
             > /etc/portage/repos.conf/azy5030.conf
           mkdir -p /etc/portage/package.accept_keywords
           echo 'dev-util/gitea-runner ~amd64' > /etc/portage/package.accept_keywords/gitea-runner
+          # Upstream tracks new Go releases faster than Gentoo stabilises them
+          # (the ebuild's BDEPEND follows upstream go.mod), so accept the
+          # testing-keyworded dev-lang/go. No stable binpkg exists for it, so
+          # this compiles Go from source when a newer one is required.
+          echo 'dev-lang/go ~amd64' > /etc/portage/package.accept_keywords/go
 
       - name: QA scan
         run: pkgcheck scan --repo /var/db/repos/azy5030 dev-util/gitea-runner

.gitea/workflows/vendor-tags.yaml

@@ -0,0 +1,43 @@
+name: Vendor tags
+# The bump script creates the `${PN}-${ver}-vendor` release (which hosts the
+# vendor tarball) *before* the bump commit exists, so its tag can only point at
+# whatever master was at the time. The PR is then squash/rebase-merged, so the
+# branch commit never lands on master either. This job re-points each vendor
+# tag at the master commit that introduced that version's ebuild. It is
+# idempotent: a tag already on the right commit is left alone.
+#
+# Only ever force-*update* a tag here. Deleting a release's tag makes Gitea
+# delete the release and its assets, which would break the ebuild's SRC_URI.
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'dev-util/**'
+
+jobs:
+  repoint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Point vendor tags at their bump commits
+        run: |
+          set -euo pipefail
+          git fetch --tags --force origin
+          for ebuild in dev-util/gitea-runner/gitea-runner-*.ebuild; do
+            ver=${ebuild##*/gitea-runner-}; ver=${ver%.ebuild}
+            tag="gitea-runner-${ver}-vendor"
+            if ! cur=$(git rev-parse --verify -q "refs/tags/${tag}^{commit}"); then
+              echo "${tag}: no such tag, skipping"; continue
+            fi
+            # git mv shows up as an addition of the new path (no --follow).
+            target=$(git log --diff-filter=A --format=%H -1 -- "$ebuild")
+            if [ "$cur" = "$target" ]; then
+              echo "${tag}: already at ${target}"; continue
+            fi
+            echo "${tag}: ${cur} -> ${target}"
+            git push --force origin "${target}:refs/tags/${tag}"
+          done

.markdownlint.json

@@ -0,0 +1,9 @@
+{
+  "MD013": false,
+  "MD024": {
+    "siblings_only": true
+  },
+  "MD060": {
+    "style": "compact"
+  }
+}

CLAUDE.md

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

Justfile

@@ -0,0 +1,70 @@
+# azy5030 overlay management commands
+
+# Install dev tooling (linters) used by the lint recipes and CI
+setup-dev:
+    brew install just markdownlint-cli shellcheck actionlint uv
+
+# Lint Markdown: all repo files, or only the .md files in a passed list
+lint-md files="":
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if [ -z "{{files}}" ]; then
+        markdownlint --ignore node_modules '**/*.md'
+    else
+        targets=$(printf '%s\n' {{files}} | grep -E '\.md$' || true)
+        if [ -n "$targets" ]; then markdownlint --ignore node_modules $targets; fi
+    fi
+
+# Lint shell scripts: all repo files, or only the .sh files in a passed list
+lint-sh files="":
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if [ -z "{{files}}" ]; then
+        targets=$(find . -name '*.sh' -not -path './node_modules/*')
+    else
+        targets=$(printf '%s\n' {{files}} | grep -E '\.sh$' || true)
+    fi
+    if [ -n "$targets" ]; then shellcheck $targets; fi
+
+# Lint YAML: all repo files, or only the .yaml/.yml in a passed list (via uv)
+lint-yaml files="":
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if [ -z "{{files}}" ]; then
+        targets=$(find . \( -name '*.yaml' -o -name '*.yml' \) -not -path './node_modules/*')
+    else
+        targets=$(printf '%s\n' {{files}} | grep -E '\.ya?ml$' || true)
+    fi
+    if [ -n "$targets" ]; then uvx yamllint $targets; fi
+
+# Lint Gitea Actions workflows: all, or only the workflow files in a passed list
+lint-actions files="":
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if [ -z "{{files}}" ]; then
+        targets=$(find .gitea/workflows \( -name '*.yaml' -o -name '*.yml' \) 2>/dev/null || true)
+    else
+        targets=$(printf '%s\n' {{files}} | grep -E '^\.gitea/workflows/.*\.ya?ml$' || true)
+    fi
+    # actionlint also runs shellcheck on each `run:` block. No custom runner
+    # labels here (workflows use ubuntu-latest), so no -config-file is needed.
+    if [ -n "$targets" ]; then actionlint $targets; fi
+
+# Autofix all Markdown files
+fix-md:
+    markdownlint --fix --ignore node_modules '**/*.md'
+
+# Apply shellcheck's auto-fixable suggestions to all shell scripts
+fix-sh:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    targets=$(find . -name '*.sh' -not -path './node_modules/*')
+    # shellcheck's diff carries ./ path segments that `git apply` rejects; strip them.
+    diff=$(shellcheck -f diff $targets 2>/dev/null | sed 's|/\./|/|g' || true)
+    if [ -n "$diff" ]; then printf '%s\n' "$diff" | git apply; fi
+
+# Lint everything (all repo files, or only a passed list of files)
+lint files="": (lint-md files) (lint-sh files) (lint-yaml files) (lint-actions files)
+
+# Autofix everything
+fix: fix-md fix-sh

dev-util/gitea-runner/Manifest

@@ -1,2 +1,2 @@
-DIST gitea-runner-1.0.4-vendor.tar.xz 3007156 BLAKE2B b9b7b03f607298a390b513bdc6824a2eba58bf7c1ed2e9e09556b309cb62669f1e5fc8fef6f62ce7a74f3a23573280158cb32d3b412394101f81cf8f19cdf64b SHA512 5309ef21c054a07b37a5ea1f5dd47cd6c424375a29f437ef743cb5719e8160e0c22a017175dad0b612291f444508b8dbe8e5fefabc9aac946c1217910aae6dd6
+DIST gitea-runner-3.4.1-vendor.tar.xz 3278360 BLAKE2B f6bc131ffd37d4d2021d8eaba1d74f2926aece0a7cf4cd0326058282c39a28e3bfc08c4bbd26696b0c1764c12ddd68160260b0366bbcf280d1e82ba4190c6c16 SHA512 823bb450f2ee714e9514f8d0c5f70744dc5322d06d9dab09abcefa25fcc15826a02eb0b7608f382ff5922a96277f0182d3db22dd265deb1c7ccf57d0103665b1
-DIST gitea-runner-1.0.4.tar.gz 326258 BLAKE2B 1908718d033b658238f735baed3323b53c85c5b5a471b8a7e543a1d7ef3898c1220a7fa27ff8e4224ae9f24960a6532699d9de770dc6ed7b5649dc0c5d624058 SHA512 5f7bdc31ce9b2c34dbac161f2a29a1be33a16a8118d9d1d58aef05de621ba542360afdb2af6fa4042d8cb7ab3421e9d1cd0f3c5102ddf85fc08a089ebb28a496
+DIST gitea-runner-3.4.1.tar.gz 501146 BLAKE2B dfc0e60d745128847903de4727ee23688e06495aca44d3baf7f3ab51765ebf4e3db239e7a66846bac24069900718f60b71bf7b3597e4c471c684076c6fdef098 SHA512 adbfe811d322ceaecacae0a6c810297541bb137dc5fbd44dbddbb4e79da288e2ee0d6b59fd168fd37ecca486daea471821990fe9685200130b320c9a2279b2d1

dev-util/gitea-runner/gitea-runner-3.4.1.ebuild

@@ -19,7 +19,7 @@ LICENSE="MIT Apache-2.0 BSD BSD-2 ISC MPL-2.0"
 SLOT="0"
 KEYWORDS="~amd64"
 
-BDEPEND=">=dev-lang/go-1.26.0"
+BDEPEND=">=dev-lang/go-1.27"
 # The runner shells out to the docker client for the Docker backend.
 RDEPEND="app-containers/docker-cli"
 

scripts/bump-version.sh

@@ -6,12 +6,17 @@
 # Expects a Gentoo environment with: go, pkgdev, git, curl, xz, jq.
 # Required env: BUMP_TOKEN, GITHUB_SERVER_URL, GITHUB_REPOSITORY.
 # Optional env: GITHUB_API_URL (defaults to ${GITHUB_SERVER_URL}/api/v1).
+#               BUMP_VERSION   target a specific upstream version (X.Y.Z, no
+#                              leading "v") instead of the latest release. An
+#                              explicit target may be older than the current
+#                              ebuild (useful to back out of a broken release).
 set -euo pipefail
 
 PN="gitea-runner"
 UPSTREAM_RSS="https://gitea.com/gitea/runner/releases.rss"
 UPSTREAM_ARCHIVE="https://gitea.com/api/v1/repos/gitea/runner/archive"
-UPSTREAM_GOMOD="https://gitea.com/gitea/runner/raw/tag"
+UPSTREAM_GOMOD="https://gitea.com/api/v1/repos/gitea/runner/raw/go.mod"
+UPSTREAM_TAGS="https://gitea.com/api/v1/repos/gitea/runner/tags"
 
 : "${BUMP_TOKEN:?BUMP_TOKEN is required}"
 : "${GITHUB_SERVER_URL:?GITHUB_SERVER_URL is required}"
@@ -25,10 +30,22 @@ host="${GITHUB_SERVER_URL#*://}"
 api() { curl -fsSL -H "Authorization: token ${BUMP_TOKEN}" "$@"; }
 
 # --- determine versions ------------------------------------------------------
-latest=$(curl -fsSL "$UPSTREAM_RSS" \
+if [ -n "${BUMP_VERSION:-}" ]; then
-  | grep -oE '<title>v[0-9]+\.[0-9]+\.[0-9]+</title>' \
+  latest="${BUMP_VERSION#v}"
-  | head -1 | sed -E 's#</?title>##g; s/^v//')
+  echo "$latest" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$' \
-[ -n "$latest" ] || { echo "could not parse upstream version"; exit 1; }
+    || { echo "BUMP_VERSION must look like X.Y.Z (got '${BUMP_VERSION}')"; exit 1; }
+  # Fail fast if the tag doesn't exist upstream, before cloning anything.
+  # (The raw endpoint silently falls back to the default branch for an
+  # unknown ref, so ask the tags API, which 404s.)
+  curl -fsSL "${UPSTREAM_TAGS}/v${latest}" -o /dev/null \
+    || { echo "upstream tag v${latest} not found"; exit 1; }
+  echo "targeting explicit version ${latest}"
+else
+  latest=$(curl -fsSL "$UPSTREAM_RSS" \
+    | grep -oE '<title>v[0-9]+\.[0-9]+\.[0-9]+</title>' \
+    | head -1 | sed -E 's#</?title>##g; s/^v//')
+  [ -n "$latest" ] || { echo "could not parse upstream version"; exit 1; }
+fi
 
 WORK=$(mktemp -d)
 git clone "${scheme}://x-access-token:${BUMP_TOKEN}@${host}/${GITHUB_REPOSITORY}.git" "$WORK"
@@ -39,11 +56,15 @@ current=$(find "$pkgdir" -name "${PN}-*.ebuild" \
   | sed -E "s#.*/${PN}-(.*)\.ebuild#\1#" | sort -V | tail -1)
 echo "upstream=${latest} current=${current}"
 
+[ "$latest" != "$current" ] || { echo "already at ${latest}"; exit 0; }
 newest=$(printf '%s\n%s\n' "$current" "$latest" | sort -V | tail -1)
-if [ "$newest" = "$current" ] && [ "$latest" != "$current" ]; then
+if [ "$newest" = "$current" ]; then
-  echo "current ($current) is newer than upstream ($latest); nothing to do"; exit 0
+  if [ -n "${BUMP_VERSION:-}" ]; then
+    echo "warning: explicit target ${latest} is older than current ${current}; downgrading"
+  else
+    echo "current ($current) is newer than upstream ($latest); nothing to do"; exit 0
+  fi
 fi
-[ "$latest" != "$current" ] || { echo "already at latest ($current)"; exit 0; }
 
 branch="bump/${PN}-${latest}"
 if api "${API}/repos/${GITHUB_REPOSITORY}/branches/${branch}" >/dev/null 2>&1; then
@@ -82,7 +103,7 @@ git checkout -b "$branch"
 git mv "${pkgdir}/${PN}-${current}.ebuild" "${pkgdir}/${PN}-${latest}.ebuild"
 
 # Track the upstream go.mod's required Go version in BDEPEND.
-goreq=$(curl -fsSL "${UPSTREAM_GOMOD}/v${latest}/go.mod" \
+goreq=$(curl -fsSL "${UPSTREAM_GOMOD}?ref=v${latest}" \
   | grep -oE '^go [0-9]+\.[0-9]+(\.[0-9]+)?' | awk '{print $2}')
 [ -n "$goreq" ] && sed -i -E \
   "s#^BDEPEND=\">=dev-lang/go-[0-9.]+\"#BDEPEND=\">=dev-lang/go-${goreq}\"#" \
@@ -99,13 +120,10 @@ printf '[azy5030]\nlocation = %s\nmasters = gentoo\nauto-sync = false\n' "$WORK"
   > /etc/portage/repos.conf/azy5030.conf
 ( cd "${pkgdir}" && pkgdev manifest )
 
-# --- validate, commit, push, open PR ----------------------------------------
+# --- commit, push, open PR ---------------------------------------------------
-pkgcheck scan --repo "$WORK" "${pkgdir}" || true
+# No emerge/pkgcheck here: pushing the branch triggers CI, which runs pkgcheck,
-mkdir -p /etc/portage/package.accept_keywords
+# builds the package from the Manifest (fetching the real release asset) and
-echo 'dev-util/gitea-runner ~amd64' > /etc/portage/package.accept_keywords/gitea-runner
+# asserts `gitea-runner --version`. A broken release shows up as a red PR.
-emerge -v --getbinpkg "=dev-util/${PN}-${latest}"
-gitea-runner --version | grep -q "v${latest}"
-
 git add -A
 git commit -m "dev-util/${PN}: bump to ${latest}"
 git push origin "$branch"
@@ -120,8 +138,7 @@ Review checklist:
 - [ ] LICENSE still covers all vendored module licenses (\`go-licenses report ./...\`)
 - [ ] BDEPEND Go version matches upstream go.mod (set to >=${goreq:-unchanged})
 - [ ] version ldflags path \`internal/pkg/ver.version\` unchanged upstream
-
+- [ ] CI (pkgcheck + emerge + \`gitea-runner --version\`) is green on this PR
-CI build + \`gitea-runner --version\` passed in this workflow.
 EOF
 )
 api -X POST -H 'Content-Type: application/json' \