Files
CV_Site_Nuxt/OKF_Nuxt/decisions/release-engineering.md
T
Noel Sabia 0a3c90cc74
PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / Lint + typecheck (pull_request) Successful in 1m11s
PR Check / Secret scan (gitleaks) (pull_request) Successful in 6s
PR Check / Dependency audit (pull_request) Successful in 9s
PR Check / Dockerfile lint (droast) (pull_request) Successful in 4s
PR Check / AI code review (opencode) (pull_request) Successful in 38s
fix(ci): create the release-please labels before the action runs
release-please finds merged release PRs by the 'autorelease: pending'
label. Gitea resolves label names with GetLabelIDsInRepoByNames, a SQL IN
filter that silently drops unknown names, so on a repository without the
labels the PR is created unlabeled and every run finds zero merged release
PRs: no tag, no release, and the next release PR instead - with a green
run each time. That is what happened to #20 and #21.

The workflow now ensures both labels exist (idempotent: list, create the
missing ones) and gained workflow_dispatch so a missed release can be
replayed.
2026-10-24 20:21:50 +02:00

109 lines
4.5 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
---
# 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.
# Recovering a release that was merged without a label
Labels exist only from the fixed workflow onwards. PRs merged before that
still carry none, so tagging them is a one-time manual step:
```sh
# add the pending label to the merged release PRs
for n in 20 21; do
curl -sS -X POST -H "Authorization: token $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"labels":["autorelease: pending"]}' \
"https://git.noelsabia.dev/api/v1/repos/CV_Website/CV_Site_Nuxt/issues/$n/labels"
done
```
Then run the release-please workflow again (it now has
`workflow_dispatch`). It creates `v1.2.0` and `v1.3.0` from those PRs'
bodies and replaces the label with `autorelease: tagged`.
# Not verified
* 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.
* That the release phase tags correctly once the label is present. The
label path is now fixed at the source; the first recovery run proves it.
# 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.