release-please config is orphaned; add the untagged-release guard if a workflow is wired up

[morphatic]

Read the exposure section first - this repo's situation differs from the other repos I am cross-posting to.

.github/release-please-config.json exists here (one package ".", release-type: node, no component), but there is no .github/workflows/release-please.yml. The workflows present are audit.yml, ci.yml, dependabot-auto-merge.yml and publish.yml.

So the config is currently orphaned - nothing reads it. That is worth resolving on its own terms (either wire up release-please or delete the stale config, so the next person does not assume releases are automated when they are not), and it means the bug below is latent here rather than live.

What happened in swephrs

Release PR morphatic/swephrs#64 (v0.13.0) merged. The release-please workflow ran and reported success. No v0.13.0 tag was created. Nothing anywhere said so - no failed check, no annotation, no comment. It surfaced days later only because someone happened to notice the tag was missing, and the release had to be cut by hand.

Tracked as morphatic/swephrs#65, fixed in morphatic/swephrs#82.

Root cause

release-please's github-release phase does not re-derive what to release from the commits. It reconstructs it by parsing the merged release PR's body.

The v0.13.0 body had been hand-enriched with better changelog prose, and that edit introduced a wrapper:

<details><summary>swephrs: 0.13.0</summary>

swephrs is a single package with no component declared, so the body release-please generates has the changelog at the top level with no <details> wrapper. Parsing a body that does have one, it read swephrs as a component name, found no package configured under that name, produced zero releases to create, and exited success - because doing nothing is not an error.

The give-away in that run's log was an empty component field:

No latest release found for path: ., component: , but a previous version (0.13.0) was specified in the manifest.

Correlation across all four swephrs release PRs - the failure tracks the wrapper, not the editing:

PR	version	body edited?	<details> wrapper?	tagged?
#56	0.12.0	yes	no	yes
#64	0.13.0	yes	yes	no
#67	0.14.0	no	no	yes
#81	0.15.0	no	no	yes

v0.12.0 was rewritten just as heavily and tagged fine, which is what made the obvious hypothesis - "editing the body breaks it" - look falsified for a while.

Your exposure

I checked this repo's .github/release-please-config.json: one package ".", no component field, include-component-in-tag: false.

That is the identical shape to swephrs. Both failure modes apply here:

1. The specific cause - if anyone ever enriches a release PR body and adds a <details><summary>...</summary> wrapper, the release will silently not tag, exactly as swephrs' did. This is an easy mistake to make, because that wrapper is release-please's own format - just for multi-package repos.
2. The silence - a release PR can merge, the workflow can go green, and no tag can exist, with nothing reporting it.

Since no workflow runs today, nothing can fail today. But the config's shape is the vulnerable one, so if release-please is ever wired up here, include the guard from day one rather than discovering this the way swephrs did.

Why the fix is a CI guard and not a rule

The narrow lesson is "never introduce a component wrapper into a release PR body". But a rule you have to remember on every release is brittle across a growing project history, and it only covers the one cause we happened to hit.

So swephrs enforces the general failure signature instead: a merged PR that still carries the autorelease: pending label. release-please relabels to autorelease: tagged only after it creates the release, so that label on a merged PR means "this merged and was never released" - regardless of what caused it.

The part worth internalizing: the failing run had already computed this. Its There are untagged, merged release PRs outstanding - aborting line is release-please finding exactly the PRs the guard queries. It knew, logged it, and exited 0. The guard only promotes an existing finding to an exit code.

This is a specific instance of a general principle: a green signal is not evidence the thing happened.

The change to make

Three edits to .github/workflows/release-please.yml.

1. Give the release-please step an id so its outputs are addressable:

      - uses: googleapis/release-please-action@v5
        id: release

2. Add a concurrency block at the top level of the workflow (after permissions:):

concurrency:
  group: release-please-${{ github.ref }}
  cancel-in-progress: false

3. Add this as the last step of the job:

      # --- Guard: a merged release PR must actually have produced a tag ---
      #
      # #65: PR #64 (v0.13.0) merged, this workflow reported `success`, and no
      # `v0.13.0` tag existed. Nothing anywhere said so; the release had to be
      # cut by hand once someone happened to notice.
      #
      # Cause: release-please's `github-release` phase rebuilds *what* to
      # release by parsing the release PR's body. This repo is a single
      # package with no `component` (see release-please-config.json, and the
      # empty `component: ` in that run's log), so the body it generates is
      # the plain top-level form. The v0.13.0 body had been enriched with a
      # `<details><summary>swephrs: 0.13.0</summary>` wrapper — correct for a
      # multi-package manifest, but here it declared a component no package
      # answers to. The phase produced zero releases and exited successfully,
      # because doing nothing is not an error.
      #
      # The guard deliberately does NOT check for that wrapper. The defect
      # worth catching is the *silence*, which any future cause would share:
      # release-please leaves a merged-but-unreleased PR labelled
      # `autorelease: pending` (it relabels to `autorelease: tagged` only
      # after creating the release), so that label on a merged PR is the
      # signature of every silent no-op, whatever caused it.
      #
      # Note what this means: the failing run had *already computed this*. Its
      # "There are untagged, merged release PRs outstanding - aborting" line is
      # release-please finding exactly the PRs queried below. It knew, logged
      # it, and exited 0. The guard only promotes that finding to an exit code.
      #
      # Turning it red beats remembering a process deviation on every release
      # — the same reason CLAUDE.md requires verifying issue closure after a
      # merge rather than trusting the PR text. A green signal is not evidence
      # the thing happened.
      - name: Verify merged release PRs were tagged
        env:
          GH_TOKEN: ${{ secrets.RELEASE_PLEASE_TOKEN || github.token }}
          REPO: ${{ github.repository }}
          TAG_NAME: ${{ steps.release.outputs.tag_name }}
        run: |
          set -euo pipefail

          # 1. If this run says it cut a release, that tag must resolve. The
          #    job has no checkout, so ask the API, not `git ls-remote`.
          if [ -n "${TAG_NAME:-}" ]; then
            if gh api "repos/${REPO}/git/ref/tags/${TAG_NAME}" >/dev/null 2>&1; then
              echo "Verified tag ${TAG_NAME} exists."
            else
              echo "::error::release-please reported it created ${TAG_NAME}, but that tag does not exist."
              exit 1
            fi
          fi

          # 2. No merged release PR may still be awaiting its release.
          untagged=$(gh pr list \
            --state merged \
            --label 'autorelease: pending' \
            --limit 50 \
            --json number,title,mergedAt \
            --jq '.[] | "  #\(.number)  \(.title)  (merged \(.mergedAt))"')

          if [ -n "$untagged" ]; then
            echo "::error::A release PR was merged but never tagged. See issue #65."
            echo "Merged release PRs still labelled 'autorelease: pending':"
            echo "$untagged"
            echo ""
            echo "release-please exited successfully without creating a release."
            echo "Most likely the release PR body was edited into a shape it could"
            echo "not parse — this repo is single-package with an unnamed component,"
            echo "so the body must stay in the plain top-level form and must NOT"
            echo "carry a '<details><summary>swephrs: X.Y.Z</summary>' wrapper."
            echo ""
            echo "To recover: restore the body to the generated form, then"
            echo "re-run this workflow (or push an empty commit to main)."
            exit 1
          fi

          echo "No merged release PRs are awaiting a tag."

The step needs no actions/checkout - it uses the API for the tag lookup precisely because the job has none.

Qualify the issue references when you paste it. The comment block says #65 and #64, which are swephrs issue numbers. Unqualified they will point at whatever issues happen to carry those numbers here. Rewrite them as morphatic/swephrs#65 and morphatic/swephrs#64 so the comment stays true.

Verify it before trusting it

Both branches were exercised against the live repo rather than assumed. Do the same here:

# Should print nothing in a healthy repo -> the guard passes
gh pr list --state merged --label 'autorelease: pending' --limit 50 --json number,title,mergedAt

# Should resolve for a real tag, and 404 for a bogus one
gh api repos/OWNER/REPO/git/ref/tags/vX.Y.Z
gh api repos/OWNER/REPO/git/ref/tags/v9.9.9

If the first command prints anything, you have an untagged release right now - that is the bug this guard exists to catch, and it would need cutting by hand before the guard can go green.

Honest limitation: this cannot be end-to-end tested until your next release PR merges. That is the point - it is the change that makes that merge self-verifying.

---

Found via: swephrs' v0.13.0 release silently failing to tag (morphatic/swephrs#65), diagnosed and fixed 2026-08-31 in morphatic/swephrs#82. Filed here because this repo runs the same release-please setup and would fail the same silent way. Cross-posted to every repo in the family that uses release-please.

[morphatic]

Correction — the snippet above has a bug. Do not paste it as filed.

The guard failed on both of its first two runs in swephrs:

failed to run git: fatal: not a git repository (or any of the parent directories): .git

gh pr list infers the repository from the local git directory, and the job deliberately has no actions/checkout — which is exactly why the tag lookup uses gh api repos/${REPO}/... rather than git ls-remote. The gh pr list call needed the same treatment and did not get it.

The fix

Add --repo "${REPO}" to the gh pr list call:

          untagged=$(gh pr list \
            --repo "${REPO}" \
            --state merged \
            --label 'autorelease: pending' \
            --limit 50 \
            --json number,title,mergedAt \
            --jq '.[] | "  #\(.number)  \(.title)  (merged \(.mergedAt))"')

REPO: ${{ github.repository }} is already in the step's env: block, so nothing else changes.

Why the verification in the original issue missed it

The issue told you to dry-run gh pr list locally, and that check passes — because a local shell is always inside the repo. The one environment difference that mattered is the one a local dry-run structurally cannot reproduce.

If you want to verify it properly, run it from a directory that is not a git repo:

cd "$(mktemp -d)"
gh pr list --repo OWNER/REPO --state merged --label 'autorelease: pending' --limit 50 --json number,title

That should return cleanly. Without --repo it reproduces the error above.

Nothing was lost

In swephrs the release-please-action step succeeded in both failing runs and opened the release PR as normal; only the verification step failed. A guard that fails loudly when it is itself broken is the safe direction — it cannot mask a real untagged release — but it is worthless until green.

Fixed in morphatic/swephrs#85.

[morphatic]

Final form of the guard — supersedes both the original issue and my first correction.

The guard needed two fixes after it shipped, and the second one changes what it checks, not just how it calls it. Use the version below; ignore the gh pr list approach in the earlier comments entirely.

Second bug: the label query was eventually consistent

gh pr list --label is served by GitHub's search index, which lags. The step runs seconds after release-please relabels the PR it has just released, so it read a stale index and failed a release that had actually completed — the tag existed, the PR was already autorelease: tagged.

Same label, same moment, two APIs:

query	result
gh pr list --label 'autorelease: pending' (search)	returned the PR
gh api repos/OWNER/REPO/pulls/N --jq '.labels[].name' (REST)	autorelease: tagged

A concurrency group stops a different run from seeing that window. It cannot stop a run from racing its own action step.

The fix: assert the invariant, not a proxy for it

The label was standing in for a fact, so assert the fact: the version release-please recorded in .release-please-manifest.json at this commit must have a tag. A release PR bumps that manifest in its own diff, so "manifest says X, no vX tag" is exactly the state a silent no-op leaves behind, whatever caused it. contents and git/ref are strongly consistent — no window to race.

This is also the check that catches the original defect, because in a silent no-op the tag_name check is skipped entirely: no release is created, so there is nothing for it to verify.

Replace the whole run: block with this:

        run: |
          set -euo pipefail

          # This job has no `actions/checkout`, so everything here goes through
          # the API: nothing may infer the repository from a local git
          # directory, and nothing may read a working copy.

          # 1. If this run reports that it cut a release, that tag must exist.
          if [ -n "${TAG_NAME:-}" ]; then
            if gh api "repos/${REPO}/git/ref/tags/${TAG_NAME}" >/dev/null 2>&1; then
              echo "Verified tag ${TAG_NAME} exists."
            else
              echo "::error::release-please reported it created ${TAG_NAME}, but that tag does not exist."
              exit 1
            fi
          fi

          # 2. The version recorded on this commit must be tagged. This is the
          #    check that catches a silent no-op, because in that case step 1
          #    is skipped entirely -- no release was created, so there is no
          #    tag_name to verify.
          version=$(gh api \
            "repos/${REPO}/contents/.github/.release-please-manifest.json?ref=${GITHUB_SHA}" \
            -H "Accept: application/vnd.github.raw" \
            | jq -r 'to_entries[0].value')

          if [ -z "${version}" ] || [ "${version}" = "null" ]; then
            echo "::error::Could not read a version from .github/.release-please-manifest.json at ${GITHUB_SHA}."
            exit 1
          fi

          if gh api "repos/${REPO}/git/ref/tags/v${version}" >/dev/null 2>&1; then
            echo "Verified v${version} is tagged (the version recorded in the manifest)."
            exit 0
          fi

          echo "::error::The manifest records ${version}, but no v${version} tag exists."
          echo "A release PR bumped the manifest to ${version}, but release-please"
          echo "created no release for it and exited 0."
          exit 1

The env: block is unchanged (GH_TOKEN, REPO: ${{ github.repository }}, TAG_NAME: ${{ steps.release.outputs.tag_name }}); GITHUB_SHA is provided by the runner.

Multi-package repos

to_entries[0].value takes the first package in the manifest. If your manifest has several entries, iterate them instead and check each version's tag under whatever tag format your include-component-in-tag setting produces — e.g. component-vX.Y.Z. The invariant is the same; only the tag spelling differs.

How to verify it properly

Do not dry-run this from inside your repo — that is how both bugs got through. Extract the literal run: block and execute it from a directory that is not a git repository, which is what CI is:

cd "$(mktemp -d)"
REPO=OWNER/REPO GITHUB_SHA=$(gh api repos/OWNER/REPO/commits/main --jq .sha) TAG_NAME= bash /path/to/guard.sh

Then replay a known-bad state if you have one: point GITHUB_SHA at a commit whose manifest version was never tagged, and confirm the guard exits 1 naming that version.

Track record, so you can judge how much to trust this

Three attempts, three bugs, all the same root mistake — verifying in an environment that differed from CI in exactly the way that mattered:

1. dry-ran gh pr list locally; passed because a local shell is always inside a git repo, and CI has no checkout
2. fixed that but kept the search-index query; passed locally because I ran it minutes after the relabel, not seconds
3. extracted the real run: block, ran it outside a git repo against the live API, and replayed the historical failure

The version above is the third one. It has since run green on its own merge commit in swephrs.

Fixed in morphatic/swephrs#86 (following morphatic/swephrs#85).