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

4.5 KiB

type, title, description, tags, status, generated, verified, sources
type title description tags status generated verified sources
Decision Release engineering Releases are produced by release-please in manifest mode, driven by conventional commits, with the message format enforced at commit time by commitizen.
decision
release
release-please
ci
draft
by at
opencode-go/glm-5.3-flash 2026-10-18T16:05:00Z
by at
human:noel not yet
id resource title
config release-please-config.json release-please configuration
id resource title
manifest .release-please-manifest.json release-please manifest
id resource title
workflow .gitea/workflows/release-please.yml 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:

# 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.