PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / Lint + typecheck (pull_request) Successful in 1m10s
PR Check / Secret scan (gitleaks) (pull_request) Successful in 6s
PR Check / Dependency audit (pull_request) Successful in 8s
PR Check / Dockerfile lint (droast) (pull_request) Successful in 5s
Removing package-name in #36 was not enough: the node strategy falls back to package.json name 'nuxt-app', so run 183 still failed with 'PR component: undefined does not match configured component: nuxt-app'.
An empty package-name is not nullish, so getBranchComponent() stays empty and matches the legacy release-please--branches--main branch. Verified by running the action's bundled release-please locally against the live Gitea API with writes intercepted: it produced POST /releases with tag_name v1.5.0 at a80c9eb and swapped #35 to autorelease: tagged. The official default release-type:node mode was tested the same way and still fails for #35.
257 lines
11 KiB
Markdown
257 lines
11 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.
|
||
|
||
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<manifest version>`. A CI or annotation tag on the same commit is
|
||
logged and ignored, and the release tag is still created.
|
||
|
||
# The release phase drops the PR on a component mismatch (2026-10-31)
|
||
|
||
With the branch kept and the label reconciled, PR #35 was still not
|
||
tagged. Run 181 (task 578, immediately after #35 merged) shows why:
|
||
|
||
```
|
||
❯ Found pull request #35: 'chore: release main'
|
||
...
|
||
⚠ PR component: undefined does not match configured component: CV_Site_Frontend
|
||
...
|
||
⚠ There are untagged, merged release PRs outstanding - aborting
|
||
```
|
||
|
||
`buildRelease()` compares the component parsed from the merged PR with the
|
||
strategy's component when the release body contains one component and that
|
||
component is empty. `include-component-in-tag: false` makes
|
||
`getComponent()` return an empty string, so the release PR is
|
||
`chore: release main` with an empty component and the branch is
|
||
`release-please--branches--main` (parsed component: undefined). But
|
||
`getBranchComponent()` ignores `include-component-in-tag` and returns
|
||
`package-name` - here `CV_Site_Frontend`. The two never match, so the
|
||
release is dropped before the tag is created.
|
||
|
||
Removing `package-name` is not enough. Run 183 (after #36 merged) shows
|
||
the node strategy falling back to the `package.json` name:
|
||
|
||
```
|
||
⚠ PR component: undefined does not match configured component: nuxt-app
|
||
```
|
||
|
||
`BaseStrategy.getDefaultPackageName()` is overridden by the node strategy
|
||
to read `package.json` `name`, so an absent `package-name` resolves to
|
||
`nuxt-app`.
|
||
|
||
The working setting is `"package-name": ""` (an empty string, not an
|
||
omitted key). An empty string is not nullish, so `getBranchComponent()`
|
||
returns empty and matches the legacy default branch
|
||
`release-please--branches--main`. This was verified by running the
|
||
action's bundled release-please 16.15.6 locally against the live Gitea
|
||
API, with writes intercepted: the release phase produced
|
||
|
||
```
|
||
POST /repos/CV_Website/CV_Site_Nuxt/releases
|
||
{"name":"v1.5.0","tag_name":"v1.5.0",...,"target_commitish":"a80c9ebf..."}
|
||
```
|
||
|
||
then swapped #35 to `autorelease: tagged`. That is release-please creating
|
||
the tag itself, not a manual `git tag`.
|
||
|
||
The action's official default mode (`release-type: node`, no manifest
|
||
config) was tested the same way and still fails for #35 with
|
||
`configured component: nuxt-app`. It cannot retroactively accept the
|
||
already-merged legacy PR; it would only help a release PR created after
|
||
the switch. The empty `package-name` is therefore the compatibility
|
||
setting that lets release-please finish v1.5.0.
|
||
|
||
# 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 live run tags #35. The exact release-phase request was verified
|
||
locally with writes intercepted (`POST /releases` with `tag_name:
|
||
v1.5.0` at `a80c9eb`); the run after merging the empty `package-name` is
|
||
the final proof.
|
||
* 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.
|