v1 Unit 3: Release pipeline — `release-version.yml`, `build-deb.yml` release mode, `stage-release.yml`, `apt-publish.yml`

[mairas]

Part of the shared-workflows v1 plan (tracking issue: issue 49).

Goal: Main-branch and release-event flows composed by callers, equivalent in output to build-release.yml and publish-stable.yml.

Requirements: R1, R2, R7

Dependencies: Unit 2

Files:

• Create: .github/workflows/release-version.yml
• Modify: .github/workflows/build-deb.yml (release mode: version inputs, changelog, rename with distro and component, artifact upload)
• Create: .github/workflows/stage-release.yml
• Create: .github/workflows/apt-publish.yml
• Create: examples/deb/.github/workflows/main.yml, examples/deb/.github/workflows/release.yml

Approach:

• Move logic from build-release.yml into the new files; do not edit build-release.yml.
• release-version.yml outputs upstream version, revision, Debian version, pre-release tag, stable tag, and whether a release is due (pre-release absent).
• stage-release.yml takes an optional artifact name; tag target is the run's commit (issue 48). Keeps draft cleanup behaviour.
• apt-publish.yml: channel input (unstable or stable), required apt-repository, apt-distro, apt-component, secret APT_REPO_PAT. In stable mode, parse tag and require an asset.
• Keep local override hooks (.github/scripts/generate-changelog.sh, rename-packages.sh, generate-release-notes.sh).
• Release notes: deb install text only when an artifact is attached; APT host derived from apt-repository.

Patterns to follow: build-release.yml step bodies; publish-stable.yml tag parsing.

Test scenarios:

• Happy path: deb canary merge → pre-release vX+N_pre and draft vX+N with the renamed .deb, dispatch unstable.
• Happy path: npm/tag-only canary merge → notes-only pre-release and draft, no deb steps, no APT secret needed.
• Edge case: rerun after pre-release already exists → release-version reports not due, downstream jobs skip, run is green.
• Edge case: first release for a new VERSION → revision 1.
• Integration: repo with legacy tags v0.3.2+4_pre and v0.3.2+4 → first v1 run creates v0.3.2+5_pre.
• Error path: workflow_dispatch of main.yml on a feature branch → release-version fails with a default-branch error; no tag created.
• Edge case: release.yml receives a pre-release event → apt-publish stable skips, run green.
• Error path: publish a legacy draft v0.5.0+3 after main moved to VERSION 0.6.0 → publish-npm fails on the tag guard before publishing.
• Integration: pre-release tag points at the run's commit even when main advanced during the run.
• Happy path: hatlabs deb canary with apt-repository: hatlabs/apt.hatlabs.fi → dispatch reaches hatlabs APT repo; notes name apt.hatlabs.fi.
• Error path: apt-publish without APT_REPO_PAT → fails with a named missing-input error.
• Happy path: publish draft on deb canary → apt-publish stable dispatches.
• Error path: published release without assets calling apt-publish stable → fails.
• Integration: compare canary's .deb filename, changelog, and release notes against its previous legacy release (R7).

Verification: One halos-org and one hatlabs deb canary produce releases equivalent to their last legacy release and reach the unstable APT channel.

[mairas]

Constraints from the review of PR 60 (build-deb.yml check mode), to hold when release mode is added here:

• Release inputs on build-deb.yml must be optional with empty defaults, and check mode must remain what runs without them. A required input breaks every v1 check-mode caller.
• A partial set of release inputs (some given, some missing) must fail in build-deb, not later in stage-release or apt-publish.
• Release mode must reuse the check-mode package lookup (repository root and build/, failing on zero packages), ideally exposed as an output, so a repo that passes PR checks does not fail at release.
• Check mode must not start generating a changelog within v1: it would overwrite a committed debian/changelog and could make lintian fail PRs that pass today.
• A package present in both the root and build/ is found twice; rename and upload must not rely on the list being duplicate-free.