Every push to main publishes a release with no promotion step

[bobtista]

Problem

release.yml triggers on push: [main], versions builds as 0.0.<run_number>, and publishes automatically. There is no human promotion decision, no pinned commit, no requirement that CI succeeded for the released SHA, and run-number versioning cannot express SemVer or hotfixes. Concretely: merging the Alpha 4 release PR (#229) would itself auto-publish a release before validation.

Proposal

• Releases run only from v*.*.* tags or a manual workflow_dispatch with an explicit ref and version.
• A promotion job verifies the ref is on main, the version is valid SemVer, and a successful CI run exists for the exact SHA.
• All build jobs check out that pinned SHA.
• Release-time tests and asset smoke checks run before publishing.

Release blocker for Alpha 4 (#307): "explicit release promotion."

[coderabbitai]

Coding Plan

Summary

• Convert release.yml from auto-publish-on-main to promotion-driven: triggered only by v*.*.* tags or a manual workflow_dispatch with explicit ref/version inputs.
• Add a first-run promote gate job that resolves the ref to an immutable SHA, verifies it is on main, validates SemVer, and confirms CI concluded success for that exact SHA, exporting sha/version/is_prerelease outputs.
• Pin every build and the release job to the promoted SHA and version (replacing 0.0.<run_number>), and run release-time tests plus asset smoke checks so publishing is blocked unless all validation passes.
• Reconcile docs/releases.md and CONTRIBUTING.md with the new promotion process.

Design Choices

Design Choice 1: How should CI success be verified for the exact release SHA?

Options Considered:

1. Query the Checks API for the SHA via actions/github-script (or gh api) and require the CI workflow's runs/check-runs to be success.
2. Use the legacy commit statuses API.
3. Use a workflow_run trigger keyed off ci.yml completion.

Chosen Option: 1

Rationale: GitHub Actions surfaces results as check runs, not legacy commit statuses, and there is no existing server-side API step in the workflows. Actions emits check runs (not statuses), and workflow_run cannot cleanly express manual promotion of an arbitrary tag/ref, so querying check runs for the pinned SHA is the accurate and flexible approach.

Design Choice 2: Should the promotion job additionally require a manual reviewer approval gate?

Options Considered:

1. Tag/dispatch-only promotion (the act of tagging or dispatching is the human decision).
2. Additionally attach the publish job to a protected release environment with required reviewers.

Chosen Option: 1

Rationale: The ticket's core requirement (human promotion decision) is already satisfied by requiring an explicit tag push or workflow_dispatch, but an environment protection rule adds an extra approval step. Option 1 is chosen as the baseline (fully satisfies the ticket with no external configuration), with the workflow structured so a protected environment: can be added to the publish job later with a one-line change if maintainers want a second approval.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Replace release triggers and introduce a promotion gate

This phase removes automatic releasing and establishes the two supported entry points (SemVer tag or manual dispatch), then adds a gate job that resolves and validates the release target before any build runs. This is the heart of the ticket: no build or publish may proceed until the ref, version, and CI status are all verified for a single pinned commit.

Task 1: Redefine release triggers and manual inputs

Switch release.yml from auto-publish-on-main to an explicitly promoted trigger model.

• Update the on: block in .github/workflows/release.yml: remove push: branches: [main]; add push: tags: ['v*.*.*']; extend the existing bare workflow_dispatch: with an inputs: block for ref (branch/SHA to release, defaulting to main) and version (SemVer string, required for manual runs).
• Keep permissions: contents: write and the concurrency group, but re-key concurrency to the resolved version/tag rather than github.ref so tag and dispatch runs for the same version coalesce.
• Note in a comment that automatic release on merge-to-main is intentionally removed (merging PR #229/Alpha-4 must no longer auto-publish).

Task 2: Add a promotion/validation gate job

Introduce a lightweight job that runs first and gates all downstream jobs via needs:, exporting the pinned SHA and normalized version as outputs.

• Add a new promote job (ubuntu-latest) at the top of release.yml that all build/release jobs depend on.
• Resolve the release ref to an immutable commit SHA: for tag triggers derive both the version (strip leading v from the tag) and the SHA the tag points to; for workflow_dispatch resolve inputs.ref to its SHA and take the version from inputs.version.
• Verify the resolved SHA is contained in main (e.g., check the commit is reachable from origin/main) and fail the job otherwise, satisfying "verify the ref is on main".
• Validate the version is valid SemVer (MAJOR.MINOR.PATCH[-prerelease][+build]) and derive an is_prerelease flag from the presence of a prerelease identifier (aligns with alpha/beta/rc conventions in docs/releases.md and UpdateChannel.Prerelease).
• Verify a successful CI run exists for the exact SHA: add an actions/github-script (or gh api) step that queries check runs / workflow runs for that SHA and requires the GenHub CI workflow to have concluded success; fail the gate otherwise.
• Expose job outputs: sha, version, is_prerelease for consumption by downstream jobs.

🤖 Prompt for AI agents

Implement the promotion-driven trigger model in `.github/workflows/release.yml`.

First, update the `on:` block: remove the `push: branches: [main]` trigger, add
`push: tags: ['v*.*.*']`, and extend the existing `workflow_dispatch:` trigger
with an `inputs:` block containing `ref` (branch/SHA to release, default `main`)
and `version` (required SemVer string). Keep `permissions: contents: write` and
the `concurrency` group, but change the concurrency key from `github.ref` to the
resolved version/tag so tag and dispatch runs for the same version coalesce. Add
a comment noting that automatic release on merge-to-main is intentionally
removed.

Second, add a new `promote` job (running on ubuntu-latest) placed at the top of
the workflow; all build and release jobs must declare `needs: promote` (or
transitively depend on it). In this job:
- Resolve the release ref to an immutable commit SHA: for tag pushes, strip the
leading `v` from the tag name to get the version and resolve the SHA the tag
points to; for `workflow_dispatch`, resolve `inputs.ref` to its SHA and use
`inputs.version` as the version.
- Verify the resolved SHA is reachable from/contained in `main`, failing the job
if not.
- Validate that the version string is valid SemVer
(`MAJOR.MINOR.PATCH[-prerelease][+build]`) and compute an `is_prerelease`
boolean from whether a prerelease identifier is present.
- Add a step using `actions/github-script` or `gh api` to query check
runs/workflow runs for the exact SHA and require the `GenHub CI` workflow to
have concluded `success`; fail the job otherwise.
- Expose job outputs `sha`, `version`, and `is_prerelease` for downstream jobs
to consume.

Phase 2: Pin all builds to the promoted SHA and version

This phase makes every build job operate on the exact validated commit and version instead of main HEAD and run_number, guaranteeing that what is released is exactly what CI validated.

Task 1: Pin Windows and Linux build jobs to the promoted SHA and version

Rework the two build jobs to consume gate outputs.

• Add needs: promote to build-windows and build-linux in .github/workflows/release.yml.
• Update each job's actions/checkout to pin ref: ${{ needs.promote.outputs.sha }} (immutable SHA, not the branch/tag), per the security guidance to release only the verified commit.
• Replace the per-job "Extract Build Info" 0.0.${run_number} computation with the promoted version from needs.promote.outputs.version; pass it to dotnet build/dotnet publish (-p:Version=) and vpk pack --packVersion unchanged otherwise.
• Update artifact names and the portable zip name to use the promoted version string.

Task 2: Pin the create-release job to the promoted SHA and version

Remove the third independent version recomputation and use gate outputs.

• Add promote to the needs: list of create-release; pin its actions/checkout to needs.promote.outputs.sha (retain fetch-depth: 0 for changelog).
• Delete the "Extract Version" step that recomputes 0.0.${run_number}; reconstruct artifact download names from needs.promote.outputs.version.
• Set the GitHub Release tag_name to v${version}, name to a SemVer-aware title, and prerelease: to needs.promote.outputs.is_prerelease (instead of the hardcoded true/"Alpha").
• Keep the existing changelog generation and softprops/action-gh-release@v2 publish step, adjusting only the version/tag/prerelease inputs.

🤖 Prompt for AI agents

Update the build and release jobs in `.github/workflows/release.yml` to consume
outputs from the `promote` gate job instead of recomputing version/ref
independently.

For `build-windows` and `build-linux`:
- Add `needs: promote` to each job.
- Update `actions/checkout` in each job to use `ref: ${{
needs.promote.outputs.sha }}` instead of the branch/tag ref, ensuring only the
verified commit is built.
- Remove the per-job "Extract Build Info" step that computes
`0.0.${run_number}`; instead use `needs.promote.outputs.version` as the version,
passing it to `dotnet build`/`dotnet publish` via `-p:Version=` and to `vpk pack
--packVersion`.
- Update artifact names and the portable zip filename to embed the promoted
version string.

For `create-release`:
- Add `promote` to its `needs:` list.
- Pin its `actions/checkout` to `needs.promote.outputs.sha`, retaining
`fetch-depth: 0` for changelog generation.
- Delete the "Extract Version" step that recomputes `0.0.${run_number}`, and
reconstruct artifact download names from `needs.promote.outputs.version`.
- Set the GitHub Release `tag_name` to `v${version}`, set `name` to a
SemVer-aware title, and set `prerelease:` from
`needs.promote.outputs.is_prerelease` instead of hardcoding `true`/"Alpha".
- Keep the existing changelog generation and `softprops/action-gh-release@v2`
publish step unchanged except for the version/tag/prerelease inputs.

Phase 3: Release-time validation before publishing

This phase ensures tests and packaged-asset integrity are re-confirmed on the pinned SHA immediately before the release is created, so a publish cannot occur if tests fail or expected assets are missing.

Task 1: Run release-time tests on the pinned SHA

Guarantee tests execute against the promoted commit before publish.

• Ensure the pinned build jobs run the platform test suites (mirroring ci.yml's test steps, excluding cross-platform test projects as CI already does) so a test failure fails the corresponding build job and blocks create-release via needs:.

Task 2: Add asset smoke checks before creating the release

Validate that all critical Velopack/portable assets are present and coherent before publishing.

• Add a verification step in create-release (after downloading/preparing final-assets/) that asserts the presence of the expected files — Windows .nupkg, RELEASES/releases.win.json, *-Setup.exe, portable zip, and Linux .nupkg — and that filenames embed the promoted version; fail the job if any are missing so the publish step never runs on incomplete assets.

🤖 Prompt for AI agents

Add release-time validation to `.github/workflows/release.yml` so publishing is
blocked unless tests pass and expected assets exist.

Ensure the pinned `build-windows` and `build-linux` jobs run the platform test
suites, mirroring `ci.yml`'s test steps (excluding cross-platform test projects
as CI already does), so that a test failure fails the corresponding build job
and, via `needs:`, blocks `create-release` from running.

In the `create-release` job, after downloading/preparing the `final-assets/`
directory, add a verification step that asserts the presence of the expected
files: Windows `.nupkg`, `RELEASES`/`releases.win.json`, `*-Setup.exe`, portable
zip, and Linux `.nupkg`. Also verify that these filenames embed the promoted
version. Fail the job if any expected asset is missing, ensuring the publish
step never runs against incomplete assets.

Phase 4: Documentation reconciliation

Bring the docs in line with the newly implemented promotion flow, since the previous docs were aspirational and CONTRIBUTING has no release/tag policy.

Update release and contribution docs

Document the tag/dispatch promotion process and the CI-success gate.

• Update docs/releases.md to describe the now-implemented flow: releasing via v*.*.* tag or manual workflow_dispatch (with ref/version), the promotion gate's checks (on main, valid SemVer, CI green for the SHA), pinned-SHA builds, and prerelease detection from SemVer suffixes; remove/correct statements implying auto-release on merge.
• Add a short "Release process / promotion" note to CONTRIBUTING.md clarifying that merging to main no longer publishes a release and that releases require explicit promotion.

🤖 Prompt for AI agents

Update documentation to reflect the newly implemented promotion-driven release
flow.

In `docs/releases.md`, describe the now-implemented flow: releasing via a
`v*.*.*` tag push or a manual `workflow_dispatch` (with `ref`/`version` inputs),
the promotion gate's checks (ref is on `main`, valid SemVer, CI concluded
`success` for the exact SHA), the fact that builds are pinned to the promoted
SHA, and prerelease detection based on SemVer suffixes. Remove or correct any
statements implying that releases are automatically published on merge to
`main`.

In `CONTRIBUTING.md`, add a short "Release process / promotion" note clarifying
that merging to `main` no longer publishes a release and that releases require
explicit promotion via tag or manual dispatch.

Research

The repo's app CI/CD lives in three GitHub Actions workflows. ci.yml builds Windows/Linux, runs tests, packages via Velopack, and uploads artifacts (no release). release.yml currently triggers on every push to main, recomputes 0.0.<run_number> independently in each job, rebuilds everything, and always publishes a prerelease "GenHub Alpha" via softprops/action-gh-release@v2. deploy.yml is unrelated (Netlify docs). There are no existing reusable workflows, composite actions, or github-script/gh api steps in CI. SemVer conventions (vMAJOR.MINOR.PATCH[-PRERELEASE]) are documented in docs/releases.md and consumed at runtime by UpdateChannel + NuGet.Versioning.SemanticVersion in VelopackUpdateManager.cs, but the actual release.yml diverges from this. Directory.Build.props holds a static fallback version overridden by CI via MSBuild props.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the promotion-driven trigger model in `.github/workflows/release.yml`.

First, update the `on:` block: remove the `push: branches: [main]` trigger, add
`push: tags: ['v*.*.*']`, and extend the existing `workflow_dispatch:` trigger
with an `inputs:` block containing `ref` (branch/SHA to release, default `main`)
and `version` (required SemVer string). Keep `permissions: contents: write` and
the `concurrency` group, but change the concurrency key from `github.ref` to the
resolved version/tag so tag and dispatch runs for the same version coalesce. Add
a comment noting that automatic release on merge-to-main is intentionally
removed.

Second, add a new `promote` job (running on ubuntu-latest) placed at the top of
the workflow; all build and release jobs must declare `needs: promote` (or
transitively depend on it). In this job:
- Resolve the release ref to an immutable commit SHA: for tag pushes, strip the
leading `v` from the tag name to get the version and resolve the SHA the tag
points to; for `workflow_dispatch`, resolve `inputs.ref` to its SHA and use
`inputs.version` as the version.
- Verify the resolved SHA is reachable from/contained in `main`, failing the job
if not.
- Validate that the version string is valid SemVer
(`MAJOR.MINOR.PATCH[-prerelease][+build]`) and compute an `is_prerelease`
boolean from whether a prerelease identifier is present.
- Add a step using `actions/github-script` or `gh api` to query check
runs/workflow runs for the exact SHA and require the `GenHub CI` workflow to
have concluded `success`; fail the job otherwise.
- Expose job outputs `sha`, `version`, and `is_prerelease` for downstream jobs
to consume.
===============================================================================

Task: 2

Update the build and release jobs in `.github/workflows/release.yml` to consume
outputs from the `promote` gate job instead of recomputing version/ref
independently.

For `build-windows` and `build-linux`:
- Add `needs: promote` to each job.
- Update `actions/checkout` in each job to use `ref: ${{
needs.promote.outputs.sha }}` instead of the branch/tag ref, ensuring only the
verified commit is built.
- Remove the per-job "Extract Build Info" step that computes
`0.0.${run_number}`; instead use `needs.promote.outputs.version` as the version,
passing it to `dotnet build`/`dotnet publish` via `-p:Version=` and to `vpk pack
--packVersion`.
- Update artifact names and the portable zip filename to embed the promoted
version string.

For `create-release`:
- Add `promote` to its `needs:` list.
- Pin its `actions/checkout` to `needs.promote.outputs.sha`, retaining
`fetch-depth: 0` for changelog generation.
- Delete the "Extract Version" step that recomputes `0.0.${run_number}`, and
reconstruct artifact download names from `needs.promote.outputs.version`.
- Set the GitHub Release `tag_name` to `v${version}`, set `name` to a
SemVer-aware title, and set `prerelease:` from
`needs.promote.outputs.is_prerelease` instead of hardcoding `true`/"Alpha".
- Keep the existing changelog generation and `softprops/action-gh-release@v2`
publish step unchanged except for the version/tag/prerelease inputs.
===============================================================================

Task: 3

Add release-time validation to `.github/workflows/release.yml` so publishing is
blocked unless tests pass and expected assets exist.

Ensure the pinned `build-windows` and `build-linux` jobs run the platform test
suites, mirroring `ci.yml`'s test steps (excluding cross-platform test projects
as CI already does), so that a test failure fails the corresponding build job
and, via `needs:`, blocks `create-release` from running.

In the `create-release` job, after downloading/preparing the `final-assets/`
directory, add a verification step that asserts the presence of the expected
files: Windows `.nupkg`, `RELEASES`/`releases.win.json`, `*-Setup.exe`, portable
zip, and Linux `.nupkg`. Also verify that these filenames embed the promoted
version. Fail the job if any expected asset is missing, ensuring the publish
step never runs against incomplete assets.
===============================================================================

Task: 4

Update documentation to reflect the newly implemented promotion-driven release
flow.

In `docs/releases.md`, describe the now-implemented flow: releasing via a
`v*.*.*` tag push or a manual `workflow_dispatch` (with `ref`/`version` inputs),
the promotion gate's checks (ref is on `main`, valid SemVer, CI concluded
`success` for the exact SHA), the fact that builds are pinned to the promoted
SHA, and prerelease detection based on SemVer suffixes. Remove or correct any
statements implying that releases are automatically published on merge to
`main`.

In `CONTRIBUTING.md`, add a short "Release process / promotion" note clarifying
that merging to `main` no longer publishes a release and that releases require
explicit promotion via tag or manual dispatch.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!