From 7ffc6d73b607d697a6086a6fe17d077ffc50d5c2 Mon Sep 17 00:00:00 2001 From: Noel Sabia Date: Sat, 31 Oct 2026 20:05:40 +0100 Subject: [PATCH] fix(ci): validate the release tag and query pending PRs by label Both PR-Agent findings were confirmed. A tag at the merge commit now counts only when it is exactly v; foreign CI or annotation tags are logged and ignored. Pending release PRs are fetched through the autorelease: pending label filter instead of paging every closed PR, so a concurrent close cannot shift a page and hide one. Also fail loudly on a merged PR without merge_commit_sha or a manifest without a version, instead of producing vundefined. Rebased on main after the separate audit fix (e0c69c1); the dependency overrides and lockfile changes from the earlier local commit were dropped. Verified on the rebased tree: lint, typecheck, build, the exact audit command, actionlint and a live dry run. --- .gitea/workflows/release-please.yml | 15 ++ OKF_Nuxt/decisions/release-engineering.md | 60 +++++++ OKF_Nuxt/log.md | 7 + OKF_Nuxt/pr-agent.md | 10 ++ scripts/reconcile-release-please.mjs | 205 ++++++++++++++++++++++ 5 files changed, 297 insertions(+) create mode 100644 scripts/reconcile-release-please.mjs diff --git a/.gitea/workflows/release-please.yml b/.gitea/workflows/release-please.yml index e074a65..7056282 100644 --- a/.gitea/workflows/release-please.yml +++ b/.gitea/workflows/release-please.yml @@ -49,6 +49,21 @@ jobs: echo "created label: ${name}" done + # The label fix above is not retroactive. PR #22 was merged with + # `autorelease: pending` but its head branch had already been deleted, + # so the action reports `Bad branch name: refs/pull/22/head`, creates no + # tag and leaves the label behind. Every later run then aborts with + # "There are untagged, merged release PRs outstanding" and never opens a + # new release PR - green, no tags. This step reconciles that state before + # the action runs: mark a pending PR tagged when its tag already exists, + # or recreate the tag when the head branch is gone and release-please + # therefore cannot. See scripts/reconcile-release-please.mjs and + # OKF_Nuxt/decisions/release-engineering.md. + - name: Reconcile stale release-please state + env: + GITEA_TOKEN: ${{ secrets.PR_GITEA_TOKEN }} + run: node scripts/reconcile-release-please.mjs + - uses: joaquinjsb/gitea-release-please-action@v4 with: # One well-scoped token for all workflow API work (see diff --git a/OKF_Nuxt/decisions/release-engineering.md b/OKF_Nuxt/decisions/release-engineering.md index 4e0e48d..d568003 100644 --- a/OKF_Nuxt/decisions/release-engineering.md +++ b/OKF_Nuxt/decisions/release-engineering.md @@ -16,6 +16,9 @@ sources: - id: workflow resource: .gitea/workflows/release-please.yml title: release-please workflow + - id: reconcile + resource: scripts/reconcile-release-please.mjs + title: release-please state reconciliation --- # Decision @@ -97,6 +100,58 @@ confirmed by comparison, not inference: while `fix/release_please` still existed, PR #23 reported `head.ref = fix/release_please`; every PR whose branch was gone reported `refs/pull//head`. +# A pending label outlives the branch and blocks every later release (2026-10-31) + +Flipping `default_delete_branch_after_merge` to `false` only protects +branches deleted *after* the change. PR #22's branch was already gone, so +its `head.ref` stayed `refs/pull/22/head` and its `autorelease: pending` +label stayed attached. Run 143 (task 475, 2026-10-27, the run immediately +after #22 merged) shows the full deadlock: + +``` +❯ Found pull request #22: 'chore: release main' +✖ Bad branch name: refs/pull/22/head +... +✔ Building candidate release pull request for path: . +❯ Found pull request #22: 'chore: release main' +⚠ There are untagged, merged release PRs outstanding - aborting +::set-output:: prs_created=false +::set-output:: releases_created=false +``` + +The first block fails the tagging phase. The second finds the same +still-pending PR and aborts the propose phase, so no new release PR is +even opened. Every later run (145, 148, 151, 153, 162, 164, 167) has the +same shape. The hand-created `v1.4.0` tag restores the baseline (`found: +v1.4.0`) but does not clear the label, so it does not break the +deadlock. This is the current reason the pipeline is still healthy-looking +and tagless. + +The workflow now reconciles that state before the action runs +(`scripts/reconcile-release-please.mjs`): + +* merged + `autorelease: pending` + a tag already at the merge commit -> + replace the label with `autorelease: tagged`; +* merged + `autorelease: pending` + head branch gone + no tag -> create + the tag from the version recorded in the manifest at the merge commit + (the exact tag release-please would have made), then swap the label; +* merged + `autorelease: pending` + head branch still present -> leave + it; release-please tags it in the same run. + +The step is idempotent and runs on every push to `main` and every manual +dispatch, so a deleted branch cannot silently poison the release pipeline +again. #20 and #21 are not labelled pending, so they do not block; their +tags remain the one-time manual recovery in the table below. + +Two details keep the reconciliation from suppressing a real release: + +* pending PRs are fetched through the `autorelease: pending` label filter, + not by paging every closed PR, so concurrent PR closes cannot shift a + page and hide one; +* a tag at the merge commit counts only when its name is exactly + `v`. A CI or annotation tag on the same commit is + logged and ignored, and the release tag is still created. + # Recovering the versions that never got a tag The label alone cannot recover them — #20, #21 and #22 all lost their head @@ -123,6 +178,11 @@ whole history. * That the release phase tags correctly once the head branch survives a merge. The next release cycle proves it. +* That the reconcile step's tag-creation fallback works with a live + token. Only the tag-already-exists path was exercised, in dry-run, + against the live PR #22. The fallback is written from the same Gitea + API shapes (`POST /tags`, `PUT /issues/{index}/labels`) the rest of the + workflow uses. * That `RELEASE_PLEASE_TOKEN_CV_SITE_NUXT` carries the `write:issue` scope the same way `PR_GITEA_TOKEN` needed it; the previous failure was an immediate API rejection consistent with a scope problem. diff --git a/OKF_Nuxt/log.md b/OKF_Nuxt/log.md index d7bf73d..ee12d04 100644 --- a/OKF_Nuxt/log.md +++ b/OKF_Nuxt/log.md @@ -1,5 +1,12 @@ # Update Log +## 2026-10-31 (PR #33 second review: release tag validated, pending PRs queried by label) + +* **Fix**: [reconcile-release-please.mjs](../scripts/reconcile-release-please.mjs) - both PR-Agent findings were confirmed. A tag at the merge commit now counts only when it is exactly `v`; a foreign CI/annotation tag is logged and ignored. Pending release PRs are fetched through the `autorelease: pending` label filter instead of paging every closed PR, so a concurrent close cannot shift a page and hide one. +* **Guard**: a merged PR without `merge_commit_sha`, or a manifest without a version, now fails loudly instead of producing `vundefined`. +* **Verified locally**: dry-run against the live repo still matches #22 to `v1.4.0`; `pnpm lint`, `pnpm typecheck`, `pnpm build` and `pnpm audit --prod --audit-level moderate` pass on the rebased tree. +* **Known issue**: PR-Agent's `/describe` posts `Failed to update PR description`; the bot token has `write:issue` but not the PR-edit scope. Recorded with the fix in [PR-Agent operations](pr-agent.md). + ## 2026-10-31 (registry host corrected: Gitea's built-in registry on git.noelsabia.dev) * **Correction**: `registry.noelsabia.dev` is gone from the documentation and the workflow. Gitea's built-in container registry is served on the Gitea hostname itself, so the image is **`git.noelsabia.dev/cv_website/nuxt:`** ([docs.gitea.com/usage/packages/container](https://docs.gitea.com/usage/packages/container/)). `registry.noelsabia.dev` was a separate hostname set up before that was known; the server-side setup is being reverted. No separate registry, no extra hostname, no extra certificate - Gitea already provides this by default. diff --git a/OKF_Nuxt/pr-agent.md b/OKF_Nuxt/pr-agent.md index c595747..efcb72c 100644 --- a/OKF_Nuxt/pr-agent.md +++ b/OKF_Nuxt/pr-agent.md @@ -52,6 +52,16 @@ access is a separate change. it, Gitea's default egress policy refuses deliveries to the Docker network. +# Known issue: "Failed to update PR description" + +On PR #33 (2026-10-31) `/describe` posted `Failed to update PR description` +before the reviewer guide. Comments work because the bot token has +`write:issue`; editing the PR body is a repository-route write and needs +`write:repository` as well. Add that scope to the `pr-agent` token and +restart the service, or remove `/describe` from `GITEA__PR_COMMANDS` if the +description update is not wanted. The review comment is still posted; this +affects only the description sync. + # Commands | Trigger | What runs | diff --git a/scripts/reconcile-release-please.mjs b/scripts/reconcile-release-please.mjs new file mode 100644 index 0000000..dcd4755 --- /dev/null +++ b/scripts/reconcile-release-please.mjs @@ -0,0 +1,205 @@ +// Repairs the release-please state that its Gitea fork cannot recover from. +// +// Why this exists (evidence in OKF_Nuxt/decisions/release-engineering.md): +// +// Gitea rewrites a merged PR's `head.ref` to `refs/pull//head` when the +// head branch is deleted. The fork parses that field as the release branch, +// logs `Bad branch name`, creates no tag - and still exits successfully. +// The merged PR keeps `autorelease: pending`, so every later run aborts with +// `There are untagged, merged release PRs outstanding` and opens no new +// release PR. That is a permanent deadlock, not a transient failure. +// +// This script runs before the action and reconciles the state: +// +// * a merged pending PR whose merge commit already has the expected +// `v` tag -> swap `autorelease: pending` for +// `autorelease: tagged` (the release exists, only the label is stale); +// * a merged pending PR whose head branch is gone and has no expected tag +// -> create the tag from the version recorded in the manifest at that +// merge commit. This is exactly the tag release-please would have made if +// the branch had survived; without it the PR blocks every future release; +// * a merged pending PR whose head branch still exists -> leave it alone, +// release-please tags it in the same run. +// +// Pending PRs are looked up by the label itself, not by paging through every +// closed PR: the set is tiny (normally zero or one) and cannot race with PRs +// closing while the pages are being read. +// +// Run locally against the public API with: +// DRY_RUN=1 node scripts/reconcile-release-please.mjs +// Reads work unauthenticated for a public repository; writes are skipped. + +const API_URL = process.env.GITHUB_API_URL +const REPOSITORY = process.env.GITHUB_REPOSITORY +const TOKEN = process.env.GITEA_TOKEN +const DRY_RUN = process.env.DRY_RUN === '1' || process.argv.includes('--dry-run') + +const PENDING = 'autorelease: pending' +const TAGGED = 'autorelease: tagged' +const MANIFEST = '.release-please-manifest.json' + +if (!API_URL || !REPOSITORY) { + console.error('::error::GITHUB_API_URL and GITHUB_REPOSITORY must be set') + process.exit(1) +} +if (!TOKEN && !DRY_RUN) { + console.error('::error::GITEA_TOKEN is required (or set DRY_RUN=1)') + process.exit(1) +} + +const repoUrl = `${API_URL}/repos/${REPOSITORY}` + +const api = async (path, init = {}) => { + const response = await fetch(`${repoUrl}${path}`, { + ...init, + headers: { + Accept: 'application/json', + ...(TOKEN ? { Authorization: `token ${TOKEN}` } : {}), + ...(init.headers ?? {}), + }, + }) + const body = await response.text() + if (!response.ok) { + throw new Error(`${init.method ?? 'GET'} ${path} -> HTTP ${response.status}: ${body.slice(0, 300)}`) + } + return body ? JSON.parse(body) : null +} + +// Gitea caps page size at 50. The label-filtered issue list is normally one +// page; loop anyway so a backlog of stale pending PRs is still reconciled. +const listAll = async (path, params = {}) => { + const items = [] + for (let page = 1; ; page++) { + const query = new URLSearchParams({ ...params, limit: '50', page: String(page) }) + const batch = await api(`${path}?${query}`) + items.push(...batch) + if (batch.length < 50) return items + } +} + +const replaceLabels = async (number, labels) => { + if (DRY_RUN) { + console.log(`[dry-run] #${number}: labels -> ${labels.join(', ')}`) + return + } + await api(`/issues/${number}/labels`, { + method: 'PUT', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ labels }), + }) +} + +const createTag = async (name, sha) => { + if (DRY_RUN) { + console.log(`[dry-run] create tag ${name} at ${sha}`) + return + } + await api('/tags', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ tag_name: name, target: sha, message: `Release ${name}` }), + }) +} + +const versionAt = async (sha) => { + const file = await api(`/contents/${MANIFEST}?ref=${sha}`) + if (!file?.content) throw new Error(`no manifest content at ${sha}`) + const manifest = JSON.parse(Buffer.from(file.content, 'base64').toString('utf8')) + // Single-package repository: the root path is ".". Keep a fallback so a + // future second package cannot silently produce `vundefined`. + const version = manifest['.'] ?? Object.values(manifest)[0] + if (!version) throw new Error(`manifest at ${sha} has no version`) + return version +} + +const run = async () => { + // One tag can point at the merge commit for a non-release reason (CI + // tooling, a manual annotation). Only the `v` tag proves + // the release exists; every other tag at that commit is ignored. + const tags = await listAll('/tags') + const tagsAtSha = new Map() + const tagSha = new Map() + for (const tag of tags) { + const sha = tag.commit?.sha + if (!sha) continue + if (!tagsAtSha.has(sha)) tagsAtSha.set(sha, []) + tagsAtSha.get(sha).push(tag.name) + tagSha.set(tag.name, sha) + } + + const pendingIssues = await listAll('/issues', { + state: 'closed', + type: 'pulls', + labels: PENDING, + }) + if (pendingIssues.length === 0) { + console.log('No merged release PR is pending - nothing to reconcile.') + return + } + + const failures = [] + const versionCache = new Map() + + for (const issue of pendingIssues) { + const pull = await api(`/pulls/${issue.number}`) + if (!pull.merged_at) continue + + const mergeSha = pull.merge_commit_sha + if (!mergeSha) { + failures.push(`#${pull.number}: merged PR has no merge_commit_sha`) + continue + } + const headRef = pull.head?.ref ?? '' + const branchGone = headRef.startsWith('refs/pull/') || headRef === '' + const labels = (pull.labels ?? []).map(label => label.name) + if (!versionCache.has(mergeSha)) versionCache.set(mergeSha, await versionAt(mergeSha)) + const expectedTag = `v${versionCache.get(mergeSha)}` + const tagsHere = tagsAtSha.get(mergeSha) ?? [] + + if (tagsHere.includes(expectedTag)) { + console.log(`#${pull.number}: ${expectedTag} already points at merge commit ${mergeSha} - marking as tagged`) + const next = labels.filter(name => name !== PENDING) + if (!next.includes(TAGGED)) next.push(TAGGED) + await replaceLabels(pull.number, next) + continue + } + + if (tagsHere.length > 0) { + console.log(`#${pull.number}: ignoring non-release tag(s) at merge commit: ${tagsHere.join(', ')}`) + } + + if (!branchGone) { + console.log(`#${pull.number}: head branch ${headRef} still exists - leaving it for release-please to tag`) + continue + } + + // The branch is gone and the expected tag is missing, so release-please + // will never get past `Bad branch name` for this PR. Recreate the tag it + // should have made, using the version the merged release PR wrote into the + // manifest. + try { + if (tagSha.has(expectedTag)) { + throw new Error(`${expectedTag} already exists at ${tagSha.get(expectedTag)}, not at merge commit ${mergeSha}; refusing to move a release tag`) + } + console.log(`#${pull.number}: head branch is gone (${headRef}) - creating ${expectedTag} at ${mergeSha}`) + await createTag(expectedTag, mergeSha) + const next = labels.filter(name => name !== PENDING) + if (!next.includes(TAGGED)) next.push(TAGGED) + await replaceLabels(pull.number, next) + } + catch (error) { + failures.push(`#${pull.number}: ${error.message}`) + } + } + + if (failures.length > 0) { + for (const failure of failures) console.error(`::error::${failure}`) + console.error('::error::release-please state is unrecoverable automatically; repair the PR/tag by hand before the next release') + process.exit(1) + } +} + +run().catch((error) => { + console.error(`::error::${error.message}`) + process.exit(1) +})