PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / Lint + typecheck (pull_request) Successful in 1m8s
PR Check / Secret scan (gitleaks) (pull_request) Successful in 6s
PR Check / Dependency audit (pull_request) Failing after 9s
PR Check / Dockerfile lint (droast) (pull_request) Successful in 4s
PR #22 kept autorelease: pending after its head branch was deleted. Gitea rewrites head.ref to refs/pull/22/head, so the action cannot tag it and every later run then aborts with 'There are untagged, merged release PRs outstanding' - no new release PR is ever opened. Add a reconciliation step that marks a pending PR tagged when its tag already exists, and recreates the tag from the manifest at the merge commit when the branch is gone and the tag is missing.
190 lines
8.1 KiB
Markdown
190 lines
8.1 KiB
Markdown
---
|
||
type: Decision
|
||
title: Release engineering
|
||
description: Releases are produced by release-please in manifest mode, driven by conventional commits, with the message format enforced at commit time by commitizen.
|
||
tags: [decision, release, release-please, ci]
|
||
status: draft
|
||
generated: { by: opencode-go/glm-5.3-flash, at: 2026-10-18T16:05:00Z }
|
||
verified: { by: human:noel, at: not yet }
|
||
sources:
|
||
- id: config
|
||
resource: release-please-config.json
|
||
title: release-please configuration
|
||
- id: manifest
|
||
resource: .release-please-manifest.json
|
||
title: release-please manifest
|
||
- 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
|
||
|
||
On every push to `main`, release-please (manifest mode) collects
|
||
conventional commits, derives the next version, and opens a release PR
|
||
that bumps `package.json`, updates `CHANGELOG.md` and moves the manifest
|
||
forward. Merging that PR creates the release. The message format that
|
||
feeds this machine is enforced locally by the commitizen pre-commit hook.
|
||
|
||
# Why
|
||
|
||
* **Manifest mode** (config JSON + manifest JSON) over inline
|
||
`release-type` in the workflow: the configuration becomes part of the
|
||
repository, reviewable in PRs, instead of buried in workflow YAML.
|
||
* **Plain tags** (`v1.0.0`, `include-component-in-tag: false`):
|
||
single-package repository; component-prefixed tags would be noise.
|
||
* **A `version` field in `package.json`**: the `node` release type reads
|
||
it; without the field the release machinery cannot track anything.
|
||
* **Enforcement at commit time**: a non-conventional message is not an
|
||
error release-please reports — it just silently produces no release.
|
||
Commitizen turns that silent failure into a blocked commit.
|
||
|
||
# How a release happens, end to end
|
||
|
||
1. Work lands on branches as conventional commits (`feat:`, `fix:`,
|
||
`chore:`, …), enforced by the local hook.
|
||
2. Merge to `main` → release-please opens/updates a release PR
|
||
(`chore(main): release …`).
|
||
3. Merge the release PR → version bumped, changelog written, tag
|
||
`vX.Y.Z` created.
|
||
|
||
# The label is load-bearing (2026-10-24)
|
||
|
||
Steps 2 and 3 are connected by a label, not by the merge alone:
|
||
|
||
* release-please creates the release PR with `autorelease: pending`;
|
||
* on the next run it lists merged PRs and keeps only those carrying that
|
||
label; those are the releases it tags.
|
||
|
||
Gitea resolves label **names** in `POST /issues/{index}/labels` with
|
||
`GetLabelIDsInRepoByNames`, which is a SQL `IN` filter: names that do not
|
||
exist are dropped **without an error**. A repository with no labels
|
||
therefore accepts the call, returns 200, and attaches nothing.
|
||
|
||
That is exactly what happened here: PRs #20 and #21 were merged as release
|
||
PRs with no label at all, so every run found zero merged release PRs,
|
||
created zero tags, and opened the next release PR instead — while reporting
|
||
success. Three release PRs, no tags.
|
||
|
||
The workflow now creates both labels (`autorelease: pending`,
|
||
`autorelease: tagged`) before the action runs. Idempotent: it reads the
|
||
label list and creates only what is missing.
|
||
|
||
# The head branch must survive the merge (2026-10-27)
|
||
|
||
The label fix was necessary but not sufficient. PR #22 carried
|
||
`autorelease: pending` when it was merged, and the run after it still
|
||
created no tag. From its log (task 475):
|
||
|
||
```
|
||
❯ Found pull request #22: 'chore: release main'
|
||
✖ Bad branch name: refs/pull/22/head
|
||
⚠ Expected 1 releases, only found 0
|
||
```
|
||
|
||
Gitea rewrites a merged PR's `head.ref` to `refs/pull/<n>/head` once the
|
||
head branch is deleted; the branch name survives only in `head.label`.
|
||
The Gitea build of release-please reads `head.ref`
|
||
(`BranchName.parse(mergedPullRequest.headBranchName)`, bundled at
|
||
`dist/index.js:15288`) and abandons the release when it is not a release
|
||
branch. GitHub keeps the branch name there, which is why the plugin's
|
||
assumption holds on GitHub and not here.
|
||
|
||
The repository deleted the head branch of every merged PR
|
||
(`default_delete_branch_after_merge: true`). It is `false` now, and a
|
||
release PR must be merged with its branch kept. The mechanism was
|
||
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/<n>/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.
|
||
|
||
# Recovering the versions that never got a tag
|
||
|
||
The label alone cannot recover them — #20, #21 and #22 all lost their head
|
||
branch, so release-please skips them for the reason above. Creating those
|
||
tags is a one-time manual step:
|
||
|
||
| Version | Merge commit |
|
||
|---|---|
|
||
| `v1.1.0` | `67cf232` (#12) |
|
||
| `v1.2.0` | `4e8aa28` (#20) |
|
||
| `v1.3.0` | `08eb042` (#21) |
|
||
| `v1.4.0` | `0c937e6` (#22) |
|
||
|
||
`v1.0.0` is the bootstrap changelog entry from the configuration commit
|
||
`c89747e` (2026-10-18); no release PR produced it.
|
||
|
||
The manifest moved to 1.4.0 without any tag existing, so until a tag is
|
||
present release-please has no baseline: it reported "No latest release
|
||
found for path: ., component: , but a previous version (1.4.0) was
|
||
specified in the manifest" and would compute the next release from the
|
||
whole history.
|
||
|
||
# Not verified
|
||
|
||
* 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.
|
||
|
||
# Revisit when
|
||
|
||
* A second package appears in the repository (then
|
||
`include-component-in-tag` and `separate-pull-requests` matter).
|
||
* A release must trigger a deploy — the workflow gains a step after
|
||
`release_created` is set.
|
||
* The label step breaks: if Gitea ever starts rejecting unknown label
|
||
names, the `Ensure release-please labels exist` step will fail loudly
|
||
instead of silently, which is the point.
|