Release Build Flow Action

Automated release creation, changelog maintenance, version syncing, tagging, and GitHub Releases using Clean Commit or Conventional Commit messages.

• Why Use This Action?
• How It Works
• Features
• Commit Type Mapping
• Quick Start
• Inputs
• Monorepo Support
• Outputs
• Examples
• Conventional Commit Examples
• Generated CHANGELOG.md Example
• Development
• Troubleshooting
• License
• Contributing
• Acknowledgments

This action turns commit history into releases with minimal workflow code. It can:

• detect semantic version bumps from commit types and breaking changes
• generate Keep a Changelog entries
• update supported manifest versions
• commit changelog and version-file updates
• create release tags and floating major tags like v1
• publish GitHub Releases
• support per-package and unified monorepo flows

graph LR
    A[Commits] --> B[Detect version bump]
    B --> C[Parse commits]
    C --> D[Generate changelog]
    D --> E[Sync version files]
    E --> F[Commit changelog]
    F --> G[Create tags]
    G --> H[Create GitHub Release]

Versioning is deterministic. When no tags exist, the action first checks package.json, Cargo.toml, pyproject.toml, or pubspec.yaml, then falls back to initial-version.

• semantic versioning from commit history
• Clean Commit and Conventional Commit support
• Keep a Changelog generation
• Clean Commit maintenance types flow into [Unreleased] until the next release
• monorepo [Unreleased] updates respect root-changelog and per-package-changelog
• optional changelog commit back to the repository
• automatic manifest version syncing for package.json, Cargo.toml, pyproject.toml, and pubspec.yaml
• GitHub Release creation with generated notes
• floating major tag updates such as v1
• monorepo package detection, per-package bumps, and unified version mode
• structured outputs for downstream workflows

Default changelog mapping:

Rules:

• BREAKING CHANGE, BREAKING-CHANGE, breaking, or ! trigger a major bump
• clean-commit defaults use feat,new,add for minor and fix,bugfix,security,perf,update,remove for patch
• conventional defaults use feat for minor and fix,perf,revert for patch
• default excluded types are docs,style,test,ci,build,release

name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: wgtechlabs/release-build-flow-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

- uses: wgtechlabs/release-build-flow-action@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    changelog-path: ./CHANGELOG.md
    sync-version-files: true
    update-major-tag: true
    release-name-template: '{tag}'

- uses: wgtechlabs/release-build-flow-action@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    prerelease-prefix: beta
    release-prerelease: true

- uses: wgtechlabs/release-build-flow-action@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    tag-only: true

Supported files: package.json, Cargo.toml, pyproject.toml, pubspec.yaml.

When monorepo: true is enabled, the action can:

• discover packages from supported workspace files
• route commits by scope, changed paths, or both
• calculate per-package or unified bumps
• generate package changelogs and a root changelog
• create package tags such as @scope/pkg@1.2.0
• optionally create a root release tag such as v1.2.0

name: Monorepo Release

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - id: release
        uses: wgtechlabs/release-build-flow-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          monorepo: true
          change-detection: both
          per-package-changelog: true
          monorepo-root-release: true

- uses: wgtechlabs/release-build-flow-action@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    monorepo: true
    unified-version: true

- uses: wgtechlabs/release-build-flow-action@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    monorepo: true
    scope-package-mapping: |
      {
        "core": "packages/core",
        "cli": "packages/cli"
      }

name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - id: release
        uses: wgtechlabs/release-build-flow-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - run: |
          echo "Version: ${{ steps.release.outputs.version }}"
          echo "Tag: ${{ steps.release.outputs.version-tag }}"
          echo "URL: ${{ steps.release.outputs.release-url }}"

- uses: wgtechlabs/release-build-flow-action@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    exclude-scopes: frontend,docs
    commit-type-mapping: |
      {
        "feat": "Added",
        "fix": "Fixed",
        "security": "Security",
        "perf": "Changed",
        "remove": "Removed"
      }

- uses: wgtechlabs/release-build-flow-action@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    release-draft: true

- id: release
  uses: wgtechlabs/release-build-flow-action@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}

- if: steps.release.outputs.release-created == 'true'
  run: |
    echo "Released ${{ steps.release.outputs.version-tag }}"
    echo "Fixed: ${{ steps.release.outputs.fixed-count }}"

Releases created with the default GITHUB_TOKEN do not trigger other workflows listening for release events in the same repository. Use a PAT or GitHub App token if you need downstream release workflows.

- uses: wgtechlabs/release-build-flow-action@v1
  with:
    github-token: ${{ secrets.GH_PAT }}

# minor
feat: add user authentication
new: support themes

# patch
fix: resolve worker leak
bugfix(auth): correct token validation
security: patch XSS issue

# major
feat(api)!: change response format

# changed
perf: improve query performance
refactor: simplify auth module
setup: update release workflow

# deprecated
deprecate: mark legacy API as deprecated

# removed
remove: delete deprecated v1 endpoints

# excluded by default
docs: update README
test: add unit tests
ci: update workflow

# Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

## [Unreleased]

## [1.2.0] - 2026-03-09

### Added

- User authentication with OAuth2

### Changed

- Improved query performance

### Fixed

- Corrected token validation

### Security

- Patched XSS vulnerability

bash run-tests.sh

- uses: wgtechlabs/release-build-flow-action@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    dry-run: true

Use a dry run first to capture the computed release plan from the action outputs, then pass the approved values back on the final run so the root release remains immutable even if new commits land before finalization. planned-version, planned-version-tag, and planned-version-bump-type are required together; planned-previous-version may be empty for a first release. Planned versions support valid SemVer, including prerelease and build suffixes. When a previous version is supplied, finalization verifies its tag still exists after fetching tags. Note that automatic tag discovery only recognizes plain X.Y.Z tags as previous releases, so if you release a prerelease or build-metadata tag (e.g., v0.1.0-beta.1+build.7), later runs will not treat it as the latest tag and will plan versions from the most recent plain X.Y.Z tag instead. This applies to single-package repositories and both unified and per-package monorepos; per-package processing continues with its normal package calculations.

- id: plan
  uses: wgtechlabs/release-build-flow-action@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    dry-run: true

- uses: wgtechlabs/release-build-flow-action@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    planned-version: ${{ steps.plan.outputs.version }}
    planned-version-tag: ${{ steps.plan.outputs.version-tag }}
    planned-version-bump-type: ${{ steps.plan.outputs.version-bump-type }}
    planned-previous-version: ${{ steps.plan.outputs.previous-version }}

Use outputs such as version-tag, release-url, packages-updated, and major-tag to chain builds, notifications, or artifact publishing.

Use version-bumping commit types such as feat, new, add, fix, bugfix, security, perf, update, or remove.

The action enforces main-branch as a production-branch guard. Run it on the configured branch or change main-branch to match your production branch.

Check changelog-enabled, exclude-types, and exclude-scopes.

Ensure:

• permissions.contents: write is set in the workflow
• create-release is true
• dry-run is false

Grant:

permissions:
  contents: write

Check workspace files, package manifests, and workspace-detection.

Use scoped commits, verify package paths, or provide scope-package-mapping.

Use a PAT or GitHub App token instead of the default GITHUB_TOKEN when another workflow depends on release events.

MIT. See LICENSE.

Contributions are welcome. See CONTRIBUTING.md.

• Keep a Changelog
• Semantic Versioning
• Clean Commit