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
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.
109 lines
4.5 KiB
Markdown
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.
|