Skip to content

Implement release-request YAML release model#462

Merged
JasonVranek merged 2 commits intoCommit-Boost:mainfrom
JasonVranek:feature/release-request-yaml-model
Apr 28, 2026
Merged

Implement release-request YAML release model#462
JasonVranek merged 2 commits intoCommit-Boost:mainfrom
JasonVranek:feature/release-request-yaml-model

Conversation

@JasonVranek
Copy link
Copy Markdown
Collaborator

@JasonVranek JasonVranek commented Apr 27, 2026

Summary

This PR refactors the release process so we can safely cut releases from a hotfix branch without having to revert main back to the last release, apply the fix, release, and then replay unrelated work.

The new model keeps the release request PR on main, but allows the referenced release commit to live off-main. The release workflow still runs from the latest workflow definition on main.

Motivation

With the old release process it's a painful sequence if we hit a production problem where a hotfix needs to ship, but main already contained additional good changes that were not release-ready:

  1. revert main back to the last release
  2. apply the hotfix
  3. cut the release
  4. re-apply the unrelated good changes

That is fragile, high-friction, and easy to get wrong.

This PR changes the process so the release request is still reviewed and merged on main, but the requested release commit can point at a dedicated hotfix branch tip instead.

Assumptions about main branch protection

This design intentionally relies on the existing branch protection and repo policy on the main repository:

  • CI must pass before code can merge to main
  • commits merged to main must be signed
  • multiple maintainers must approve merges to main
  • release tags may only be created by the GitHub App used in the release gate workflow

Given those guarantees, the release automation does not need to duplicate main's branch-protection checks. The release request PR is the approval point. The release gate is the last authoritative check before tag creation.

New release flow

  1. A PR on main adds .releases/vX.Y.Z.yml

    • the filename is the release tag
    • the YAML contains the target commit SHA and reason
    • the target commit may be on main or on an off-main hotfix branch
  2. validate-release-request.yml

    • runs on the PR
    • provides fast pre-merge feedback
    • validates request shape only
  3. release-gate.yml

    • runs after merge
    • re-validates the request
    • creates the tag via the GitHub App
    • dispatches the release workflow from main
  4. release.yml

    • runs from the latest workflow definition on main
    • accepts only the tag as input
    • resolves the commit from the tag itself
    • builds binaries from that exact tagged commit
    • pushes Docker images
    • signs artifacts with Sigstore
    • drafts the GitHub Release

Security and trust model

The tag is now the trust anchor.

We intentionally do not trust a free-form tag and commit pair passed into the release workflow. Instead:

  • release-gate.yml creates the tag via the GitHub App
  • release.yml receives only the tag
  • release.yml resolves the commit from the tag before building

This keeps the latest workflow logic on main while preventing dispatch-time injection of an arbitrary tag and commit pair.

What was simplified

This PR removes release-time checks that duplicate guarantees already enforced by main branch protection, or that created unnecessary operational friction:

  • removed release-time CI checking
  • removed extra ancestry restrictions that prevented off-main hotfix releases
  • removed signature verification from release automation
  • simplified gate validation to only the invariants that still matter:
    • valid release filename
    • valid YAML schema
    • commit exists
    • tag does not already exist

This PR also keeps the release request model intentionally simple:

  • release request files are immutable after merge
  • botched attempts may leave version gaps
  • we accept those gaps rather than adding retry-specific state or mutable pre-tag behavior

Operational notes

  • validate-release-request.yml remains intentionally separate from release-gate.yml

  • it is not the security boundary

  • it is there to provide fast feedback before merge and reduce merge-then-fail churn

  • release assets are published per binary:

    • commit-boost-cli-...
    • commit-boost-pbs-...
    • commit-boost-signer-...
  • release asset verification now uses the release workflow identity on refs/heads/main, since the workflow runs from main even when building an off-main tagged commit

Additional cleanup

This PR also includes:

  • tighter workflow permissions with write scopes only where required
  • removal of dead release-process code and tests
  • documentation updates for the new hotfix-capable model
  • removal of GHCR registry caching in release builds to avoid fork/package ACL failures during testing

###Testing

Covered failure and edge-path testing includes:

  • invalid release filenames
  • invalid YAML schema
  • nonexistent commit SHAs
  • existing tag reuse
  • multiple release files in one PR
  • modifications to existing release request files
  • gate behavior for zero and multiple added release files
  • off-main hotfix branch release commits
  • tag-only dispatch / resolve-tag behavior
  • :latest behavior for RCs and stable releases

Closes #457

@JasonVranek JasonVranek requested a review from a team April 27, 2026 18:21
ltitanb
ltitanb previously approved these changes Apr 27, 2026
Comment thread README.md Outdated
Comment thread .github/workflows/release.yml
@JasonVranek JasonVranek merged commit cd5b788 into Commit-Boost:main Apr 28, 2026
3 checks passed
@JasonVranek JasonVranek deleted the feature/release-request-yaml-model branch April 28, 2026 14:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Update node versions used by tools in CI

3 participants