Important

To ensure changelogs are generated correctly, all git commit messages must follow the Conventional Commits specification.

Also, you must go to your repository Settings > Actions > General > Workflow permissions and enable "Allow GitHub Actions to create and approve pull requests", otherwise the automated release process will fail.

Every Pull Request from a prerelease/* branch to its persistent release/* branch must be merged using "Create a merge commit" instead of "Squash and merge" or "Rebase and merge".

🚀 Instant Magic for Your Repository!!!

Add professional release automation to your personal project with a single step:

Copy the prepare-release.yml and publish-release.yml files from .github/workflows into your project's .github/workflows directory.

✨ That's it! Your repository is now enchanted.

⚠ Breaking Change

Migration Guide
v1 to v2

⚙ How It Works

This workflow streamlines your release process into a few simple steps:

1. Tag Your Release: On your development branch (separate from master or main), create a git tag with a v prefix (e.g., v1.0.0).

   git tag v1.0.0

2. Push the Tag: Push the tag to GitHub.

   git push origin v1.0.0

3. Automated Magic: GitHub Actions will automatically:

   • Generate a changelog based on your conventional commits.
   • For a stable release without preceding prereleases, create only release/<stable-tag> at the tagged commit and open its Pull Request directly to the main branch.
   • For the first prerelease, create release/v<stable-version> and prerelease/<tag> branches at the tagged commit, and open a Pull Request to the persistent release branch.
   • For later prereleases, create prerelease/<tag> branch at the tagged commit, and open a Pull Request to the same persistent release branch.
   • For the stable release that concludes the prerelease series, merge prerelease/<stable-tag> into the persistent release branch and then promote the release branch to the main branch through a second Pull Request.

4. Review and Merge: Review the Pull Request created by the bot.

   • Do not modify the Pull Request title or body, as they are used for the release metadata.
   • Merge the Pull Request.
   • The workflow will automatically create coordinated releases across GitHub and supported package registries.
   • The workflow will automatically cherry-pick the release changelog commit back to the configured development branch (develop by default).

📦 Optional Publishing

Note

If the required inputs or secrets for a release target are not configured, publishing for that target will not start.

Configure target publishing in your user-side entry workflow (.github/workflows/publish-release.yml):

Release Target	Required	User-Side Inputs (with)
GitHub Release	ACCESS_TOKEN (Mapped from secrets.GITHUB_TOKEN)	None
NPM	NPM_TOKEN	npm-node-version (Default 20) npm-package-dir (Default .) npm-deploy-command (Default npm run deploy)
TODO Requirement Blueprint (Bump Project Node Version)	trb-repository trb-project-node-name

🪆 Mono-repo Support

This workflow also releases individual sub-packages inside a mono-repo. Each sub-package gets its own version, changelog and GitHub Release, while the overall flow stays identical to the monolith case.

1. Declare your sub-packages

   In your user-side entry workflow (.github/workflows/prepare-release.yml), declare every sub-package as a name → workspace mapping via the packages input, and add the sub-package tag pattern to the trigger:

   on:
     push:
       tags:
         - 'v*'    # Monolith release.
         - '*/v*'  # Mono-repo sub-package release.
   
   
   jobs:
     call-prepare:
       uses: leoweyr/github-release-workflow/.github/workflows/reusable-prepare-release.yml@v2.1.0
       with:
         packages: |
           {
             "core": "packages/core",
             "cli": "packages/cli"
           }
       secrets:
         ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}

   The workspace is the work directory that binds a sub-package's changes. Only commits that touch files inside it are considered for that sub-package's changelog.

   Likewise, sub-packages that need different publish settings are configured via the package-overrides input in your user-side entry workflow (.github/workflows/publish-release.yml), the same way as packages:

   jobs:
     call-publish:
       uses: leoweyr/github-release-workflow/.github/workflows/reusable-publish-release.yml@v2.1.0
       with:
         package-overrides: |
           {
             "core": {
               "npm-package-dir": "packages/core"
             },
             "cli": {
               "npm-package-dir": "packages/cli"
             }
           }
       secrets:
         ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

2. Tag a sub-package release

   Use a tag in the form <package>/v<semver>:

   git tag core/v1.0.0
   git push origin core/v1.0.0

How it differs from a monolith release:

Aspect	Monolith	Mono-repo Sub-package
Trigger Tag	v1.0.0	core/v1.0.0
Release Pull Request Title	release: v1.0.0	release: core@v1.0.0
Changelog Commit Range	Latest commit → previous v* tag	Latest commit → previous core/v* tag
Commit Filtering	All conventional commits	Only commits that modified files inside the sub-package workspace
Changelog Location	CHANGELOG.md (project root)	packages/core/CHANGELOG.md (inside the workspace)
GitHub Release Title	1.0.0	core@v1.0.0