Why the Best Release Is the Boring Release

If pushing a new version still triggers adrenaline—calendar invites, “is prod ready?” threads, last-minute version debates—you’re paying operational tax every sprint. Boring releases aren’t a vibe; they’re an engineering prerequisite for reliability, velocity, and trust.

This article hands you a working, language-agnostic release system you can drop into almost any repo:

• Conventional commits → automatic semantic versioning
• vnext → fast, deterministic version calc + CHANGELOG generation
• Two small GitHub Actions workflows instead of a monolithic pipeline
• Optional patching of versions across YAML, README, Helm, and package files
• Support for Node, Rust, containers, Helm (and easy to extend)
• PATs or Deploy Keys so tags can trigger downstream builds
• CHANGELOGs that populate your GitHub Releases (and Renovate PRs)

By the end, “release” = merge to trunk. The rest is automated.

The Philosophy: Separate the Concerns, Shrink the Pieces

Most release pain comes from two anti-patterns:

1. Monolithic pipelines: a single, everything-bagel workflow that lints, builds, tests, versions, publishes, promotes, notarizes, and makes the coffee. One failure blocks all; one change risks all.
2. Human-selected versions: emotion-laden meetings about whether the change is “worthy” of 2.0. The version becomes branding, not a signal of change risk.

Fix both:

• Split versioning from building/publishing.
  • Pipeline A (on trunk push): lint, test, compute next version, patch files, tag, write CHANGELOG.md.
  • Pipeline B (on tag push): build, publish artifacts/images, create GitHub Release, optionally promote to environments.
• Infer the version from conventional commits. No meetings. No guessing. Features → minor, fixes → patch, breaking changes → major.

This gives you tiny, composable “LEGO blocks” you can reuse across repos and stacks.

Conventional Commits → Semantic Versioning, in One Minute

Adopt this lightweight commit format (the Conventional Commits spec):

• feat: add dark mode toggle → minor bump
• fix: revert incorrect auth redirect → patch bump
• refactor: / docs: / chore: → usually patch or no release
• Breaking change: include BREAKING CHANGE: in the commit body → major bump

Example breaking commit:

feat(auth): replace legacy session flow

BREAKING CHANGE: The `/session/renew` endpoint was removed.
Use `/v2/auth/refresh` instead.


The commit log becomes data for version calculation and copy for your CHANGELOG.

Meet vnext: A Blazing-Fast, Language-Agnostic Version Engine

vnext is a tiny Rust CLI that:

• Scans your git history
• Computes the next semver from conventional commits
• Outputs vX.Y.Z
• Optionally generates a changelog
• Can patch versions across multiple files (via simple workflows)

Install with UBI (Universal Binary Installer)

ubi --project unbounded-tech/vnext


Get the next version (stdout)

NEXT_VERSION=v"$(vnext)"
echo "$NEXT_VERSION"   # => v1.8.1


Generate a CHANGELOG

vnext --changelog > CHANGELOG.md


That’s the core. Now let’s wire it into GitHub Actions.

The Two-Workflow Release Pattern (Copy/Paste)

Workflow A — “On Push to Trunk: Version & Tag”

Trigger: push to main (or master)
Goal: lint/test → compute new version → patch files → write changelog → create tag (e.g., v1.8.1)

# .github/workflows/version-and-tag.yml
name: On Push Main, Version and Tag

on:
 push:
   branches:
     - main
     - master

permissions:
 packages: write
 contents: write

jobs:
 version-and-tag:
   uses: unbounded-tech/workflow-vnext-tag/.github/workflows/workflow.yaml@v1
   with:
     useDeployKey: true          # or usePAT: true
     changelog: true             # writes CHANGELOG.md
     # Optional: language-aware updates
     # node: true
     # rust: true
     # Optional: patch Helm, YAML, README, etc.
     # yqPatches: |
     #   patches:
     #     - filePath: helm/values.yaml
     #       selector: .image.tag
     #       valuePrefix: "v"
     # regexPatches: |
     #   patches:
     #     - filePath: README.md
     #       regex: /Current version: v[0-9]+\.[0-9]+\.[0-9]+/g
     #       valuePrefix: "Current version: v"


What this does:

1. Runs your quality checks (lint/test/build if defined)
2. Computes the next version via vnext (e.g., v1.8.1)
3. Patches versioned files (e.g., package.json, Helm charts)
4. Writes CHANGELOG.md from commit history
5. Tags the repo with v1.8.1 and pushes the tag

🔐 Important: The default GitHub token won’t trigger downstream tag workflows. Use a Deploy Key or a PAT so the tag push fires Workflow B.

Workflow B — “On Tag: Build, Publish, Release”

Trigger: push with tags: v*.*.*
Goal: build artifacts/container, publish, create GitHub Release with changelog body

Example: Simple GitHub Release

# .github/workflows/release.yml
name: On Version Tag, Create Release

on:
 push:
   tags:
     - 'v*.*.*'

permissions:
 contents: write

jobs:
 release:
   uses: unbounded-tech/workflow-simple-release/.github/workflows/workflow.yaml@v1
   with:
     tag: ${{ github.ref_name }}
     name: ${{ github.ref_name }}


Example: Rust Binaries

# .github/workflows/release-rust.yml
name: On Version Tag, Build & Publish Rust Binaries

on:
 push:
   tags:
     - 'v*.*.*'

permissions:
 contents: write

jobs:
 build-and-release:
   uses: unbounded-tech/workflows-rust/.github/workflows/release.yaml@v1
   with:
     binary_name: ${{ github.event.repository.name }}
     build_args: "--release --features vendored"


Example: Containers + Helm GitOps Promote

# .github/workflows/publish-and-promote.yml
name: On Tag: Publish Image, Create Release, Promote

on:
 push:
   tags:
     - 'v*.*.*'

permissions:
 contents: write
 packages: write
 issues: write
 pull-requests: write

jobs:
 publish:
   uses: unbounded-tech/workflows-containers/.github/workflows/publish.yaml@v1.1.1

 release:
   needs: publish
   uses: unbounded-tech/workflow-simple-release/.github/workflows/workflow.yaml@v1
   with:
     tag: ${{ github.ref_name }}
     name: ${{ github.ref_name }}

 promote:
   needs: release
   uses: unbounded-tech/workflows-gitops/.github/workflows/helm-promote.yaml@v1
   secrets:
     GH_PAT: ${{ secrets.GH_PAT }}  # PAT for cross-repo writes
   with:
     environment_repository: your-org/staging-env
     path: .gitops/deploy
     project: staging


⚠️ Deploy keys can’t push to other repos (e.g., your env repo). For cross-repo GitOps promotes, use a PAT or GitHub App credentials.

Credentials: Deploy Key vs PAT (and Why Your Tag Didn’t Trigger)

By design, the default GITHUB_TOKEN doesn’t trigger other workflows to prevent runaway loops. To allow the tag push from Workflow A to start Workflow B, use one of:

• Deploy Key (per-repo SSH key; doesn’t grant cross-repo access)
• PAT (Personal Access Token; can be org-scoped for many repos)
• GitHub App (more setup; great for large orgs)

One-Time Setup: Generate a Deploy Key via vnext

# refresh GitHub CLI with key management scopes
gh auth refresh -h github.com \
 -s admin:public_key -s admin:ssh_signing_key

export GITHUB_TOKEN="$(gh auth token)"

# inside your repository
vnext generate-deploy-key


This creates the Deploy Key and wires it into the repo secrets. From now on, the version-and-tag workflow can push tags that trigger your release workflow.

On GitHub free tier, org-wide secrets aren’t available; Deploy Keys keep setup local to each repo. On paid orgs, a PAT is usually simpler at scale.

Patching Versions Across Files (Helm, README, YAML)

The shared workflow lets you update version strings without writing custom scripts.

Patch Helm Charts with yqPatches

with:
 yqPatches: |
   patches:
     - filePath: helm/values.yaml
       selector: .image.tag
       valuePrefix: "v"
     - filePath: helm/Chart.yaml
       selector: .version
       valuePrefix: "v"


Patch Arbitrary Files with regexPatches

with:
 regexPatches: |
   patches:
     - filePath: package/composition.yaml
       regex: /ghcr\.io\/org-name\/package-name:(.*)/g
       valuePrefix: "ghcr.io/org-name/package-name:v"
     - filePath: README.md
       regex: /Current version: v[0-9]+\.[0-9]+\.[0-9]+/g
       valuePrefix: "Current version: v"


Language-Aware Bumps

Set node: true or similar flags where supported to let the workflow update package manifests using native tooling.

CHANGELOGs That Actually Help People

A CHANGELOG isn’t just nice to have; it’s your developer communications channel. Because vnext uses commit data, your release notes are always in sync with what changed.

• Generated into CHANGELOG.md
• Committed along with the tag/version bump
• Used as the body of the GitHub Release
• Surfaced in Renovate PRs so consumers see what changed

Tip: Use Squash & Merge and write a clear title/body for each PR—the body becomes great release notes.

End-to-End Examples by Stack

Node Library

• Workflow A updates package.json/package-lock.json and tags
• Workflow B publishes to npm + GitHub Release

# version-and-tag.yml (Node bump)
with:
 node: true
 changelog: true


# release-node.yml (example skeleton)
name: On Tag: Publish to npm

on:
 push:
   tags: ['v*.*.*']

permissions:
 contents: write

jobs:
 release:
   runs-on: ubuntu-latest
   steps:
     - uses: actions/checkout@v4
     - uses: actions/setup-node@v4
       with:
         node-version: '20'
         registry-url: 'https://registry.npmjs.org'
     - run: npm ci
     - run: npm publish
       env:
         NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
     - uses: softprops/action-gh-release@v2
       with:
         tag_name: ${{ github.ref_name }}
         body_path: CHANGELOG.md


Rust CLI

Use the shared Rust workflow (shown earlier) to build binaries for multiple targets and attach to the release.

Containerized App + Helm Promote

Build/push image → create release → update env repo via GitOps workflow (shown earlier).

A Practical Commit Taxonomy (Cheat Sheet)

• feat(scope): … → minor
• fix(scope): … → patch
• perf(scope): … → patch
• refactor(scope): … → patch/no-op (depends on your policy)
• docs: …, chore: …, test: … → no release (unless you choose otherwise)
• feat!: … or body with BREAKING CHANGE: → major

Guideline: Default to patch unless you’re shipping a user-visible capability (feat) or a breaking change.

Monorepos, Poly-Repos, and Release Trains

• Poly-repo: Each repo runs the two-workflow pattern. Easy.
• Monorepo:
  • Option A: One version for the whole repo (simple, but noisy).
  • Option B: Path-scoped versioning (best). Compute the next version from commits in that path, tag with a prefix (e.g., ui/v1.3.0, api/v2.4.1). You can adapt vnext invocation and workflow filters for this.
• Release trains: If you ship multiple services together, drive a meta-repo that tags/pins component versions, then triggers coordinated promotions.

Beyond Basics: Make It Enterprise-Grade (Still Boring)

You can bolt on more quality gates without bloating the core:

• SLSA provenance + SBOM (Syft) generation
• Container signing (cosign)
• Secret scanning (Gitleaks, TruffleHog)
• IaC linting (tfsec, kubeval)
• License compliance checks
• Canary deploy + automated rollback
• DORA metrics export (lead time, deployment frequency, MTTR)

Each gate remains a small, independent workflow reused across repos.

Troubleshooting & FAQ

Q: I tagged, but the release workflow didn’t run.
A: The default GITHUB_TOKEN can’t trigger other workflows. Use a Deploy Key (per repo) or PAT (org-scoped). Verify the tag push came from that credential.

Q: My changelog is empty or wrong.
A: Check commit formatting. Use Squash & Merge and write meaningful PR titles/bodies. Ensure your repo’s CI uses full git history (avoid shallow clones if you changed defaults).

Q: We don’t want devs fussing with commit types.
A: Add a PR template with examples, enforce with a commit-lint hook (many exist), and teach “if you add a capability, it’s feat.”

Q: Can I opt out of releases for some commits?
A: Yes. Use chore:/docs:/test: (or your org’s chosen no-release labels). Configure your policy in vnext/workflows if you need stricter rules.

Q: How do we hotfix?
A: Branch from the latest tag (or main), commit a fix: with only the fix, merge to trunk. The version will bump patch and tag automatically. If you must patch an older line, run the same two-workflow pattern on a maintenance branch.

Q: Can marketing still say “2.0”?
A: Sure—just ship the breaking changes that justify a major. The number reflects the nature of change instead of advertising it.

The Human Side: How to Roll This Out (Without Drama)

1. Announce the goal: “Releases should be a non-event.”
2. Adopt conventional commits: lightweight, pragmatic.
3. Install vnext + workflows in a pilot repo.
4. Demo the boring path: merge to trunk → get a tag, build, release, changelog.
5. Template: create a workflow-templates repo and point teams to it.
6. Instrument: track time-to-release and release failures before/after.
7. Iterate: add gates (SBOM, signing) once the boring core is stable.

Copy-Ready Snippets (All in One Place)

Install vnext

ubi --project unbounded-tech/vnext
vnext --version


Compute + Changelog (local test)

NEXT_VERSION=v"$(vnext)"
echo "$NEXT_VERSION"
vnext --changelog > CHANGELOG.md


Deploy Key for Tagging (one-time per repo)

gh auth refresh -h github.com \
 -s admin:public_key -s admin:ssh_signing_key
export GITHUB_TOKEN="$(gh auth token)"
vnext generate-deploy-key


Workflow A (version & tag)

name: On Push Main, Version and Tag
on: { push: { branches: [ main, master ] } }
permissions: { packages: write, contents: write }
jobs:
 version-and-tag:
   uses: unbounded-tech/workflow-vnext-tag/.github/workflows/workflow.yaml@v1
   with:
     useDeployKey: true
     changelog: true
     # node: true
     # rust: true
     # yqPatches: |
     #   patches:
     #     - filePath: helm/values.yaml
     #       selector: .image.tag
     #       valuePrefix: "v"
     # regexPatches: |
     #   patches:
     #     - filePath: README.md
     #       regex: /Current version: v[0-9]+\.[0-9]+\.[0-9]+/g
     #       valuePrefix: "Current version: v"


Workflow B (release)

name: On Version Tag, Create Release
on: { push: { tags: [ 'v*.*.*' ] } }
permissions: { contents: write }
jobs:
 release:
   uses: unbounded-tech/workflow-simple-release/.github/workflows/workflow.yaml@v1
   with:
     tag:  ${{ github.ref_name }}
     name: ${{ github.ref_name }}


What “Boring” Buys You

• Predictability: shipping is just another CI run
• Speed: no ceremony, no manual steps, no “what version?” debates
• Signal: version numbers encode risk; CHANGELOGs tell the story
• Reusability: tiny cross-repo workflows reduce maintenance
• Trust: consumers see what changed and why—right inside PRs and releases

Boring is not bland; boring is battle-tested. Your future outages will come from real problems, not release choreography.

Final Checklist

• Conventional commits adopted (PR template + quick guide)
• vnext installed via UBI
• Deploy Key or PAT set; tag pushes trigger workflows
• version-and-tag.yml in place (changelog on)
• release.yml in place (artifacts, images, or binaries)
• Optional: yq/regex patches configured
• Renovate consuming release notes
• Document hotfix and maintenance branch playbook
• Measure before/after lead time to confirm the win

‍