release-please: Automating Release PRs from Conventional Commits

The Problem: Release Drudgery and Manual Changelogs

Releasing a library or application involves writing a changelog, bumping version numbers, tagging a commit, and creating a GitHub release. Doing this by hand is error-prone and tedious, especially when multiple features and fixes land between releases. release-please automates the generation of changelogs and version bumps by reading your git history for conventional commit messages. It targets developers who already follow the conventional commits spec and want a bot to prepare release pull requests that they can review and merge. It is not a package publisher and it does not handle complex branch management, so teams that need those features must look elsewhere.

The Release PR Workflow: Merge to Release

Instead of releasing every commit to the default branch, release-please maintains a release PR that stays up to date as new work merges. The release PR contains the changelog and version bump. When you are ready to tag a release, you merge that PR. On merge, release-please updates the changelog file and language-specific files like package.json, tags the commit with the version number, and creates a GitHub release from that tag. The README lists three lifecycle labels: autorelease: pending before merge, autorelease: tagged after merge and tag, and autorelease: snapshot for snapshot version bumps. It also mentions autorelease: published as a convention that publication tooling can add, though release-please does not add it automatically. This design gives you a human review point before anything is tagged, which is a deliberate trade-off: releases are not immediate, but they are controlled.

How It Parses Commits: Prefixes, Footers, and Overrides

release-please relies on conventional commit prefixes to determine version bumps. A fix: prefix maps to a patch, feat: to a minor, and a trailing exclamation mark like feat!: or fix!: indicates a breaking change and triggers a major. The README also lists deps as a releasable unit, while chore and build are not. This means a PR that only contains chore commits will not produce a release PR. To handle a PR with multiple changes, release-please allows a single commit message to carry several conventional messages as footers, each with its own scope and optional BREAKING-CHANGE footer. The README shows an example where a commit contains a feat, a fix with a breaking change, and another feat, all in one message. For fixing mistakes after a merge, you can edit the body of the merged PR and add a BEGIN_COMMIT_OVERRIDE section that replaces the commit message for release notes. This override only works with squash-merges, because release-please cannot determine which commit to apply it to with plain merges.

Getting It Running: Commands and Configuration

The repository is published on npm, and package.json defines a release-please binary. The README gives a concrete example for forcing a version: run git commit --allow-empty -m "chore: release 2.0.0" -m "Release-As: 2.0.0". The Release-As footer in the commit body tells release-please to open a PR for that exact version. This is a simple, auditable way to override automatic versioning. The README explains that release-please creates a release PR after it notices releasable units on the default branch since the last release. For the GitHub application, it will not create a new PR if an existing PR has the autorelease: pending label, so you may need to remove that label manually if a release is already done.

A Genuine Limitation: Stale Labels and Missed Releases

A common failure mode is that release-please does not create a release PR when you expect it. The README dedicates a whole section to this. Step 1 is to ensure releasable units are present, since chore-only commits do not count. Step 2 warns about stale autorelease: pending or autorelease: triggered labels on old PRs. GitHub API failures can leave these labels in place, and release-please then thinks a release is still pending and blocks new PRs. The fix is to manually remove the label and rerun. This is a real operational burden: you need to monitor labels and occasionally clean them up. The README also notes that the commit override feature fails with plain merges, so if your team does not enforce squash-merges, you lose that correction mechanism and your changelog can include noisy commits.

When It Is the Wrong Tool: Publication and Branching

release-please explicitly does not publish to package managers. After merging the release PR, you still need separate tooling to run npm publish, twine upload, or similar. It also does not handle complex branch management, so if you maintain multiple release branches or need to backport fixes, release-please will not coordinate that. The README states this plainly: "It does not handle publication to package managers or handle complex branch management." For teams that need immediate releases on every merge, the release PR model adds latency. If you prefer a fully automated pipeline that tags and publishes without a human merge step, release-please's manual merge gate is a mismatch.

Alternative Approach: Direct Release on Merge

A common alternative is a tool that runs release steps immediately after a commit lands on the default branch, rather than maintaining a release PR. For example, semantic-release (a popular Node.js tool) analyzes commits, determines the next version, updates the changelog, tags, and publishes to npm in one automated workflow. The key difference is that semantic-release releases on every push to the main branch, with no manual merge of a release PR. This suits projects that want zero-touch releases and do not need a human review point. In contrast, release-please gives you a PR to review and merge, which is better for projects that require a changelog review before tagging. The trade-off is speed versus control. If your team values a human gate, release-please fits; if you want full automation, semantic-release is a direct alternative.

Maintenance and License Considerations

release-please is actively maintained, with version 17.11.2 released in August 2026. The repository is licensed under Apache-2.0, which permits commercial use, modification, and distribution, with the requirement to include the license and attribution. You should review the full license text for your specific use case. Being a Google-maintained project, it has a track record of updates, but you should still plan for occasional breaking changes in major versions. The configuration lives in your repository, and the tool's behaviour can change with updates. You should verify the current configuration options in the official docs before upgrading, as version 17.x may have changed defaults from earlier versions.

Editorial conclusion

Adopt release-please if your team uses conventional commits, squash-merges, and a single default branch, and you want a bot that maintains release PRs until you merge them. Avoid it if you need package publication, complex branch management, or if your history is full of merge commits that obscure releasable units. Before adoption, verify that your commit prefixes align with the releasable unit list (feat, fix, deps, plus language-specific ones), and that you can enforce squash-merges, because the commit override feature and clean changelogs depend on linear history. Also check the existing labels on old PRs, as stale autorelease labels can block new release PRs. If you need more control over the release process, consider a tool that runs release steps directly on merge rather than through a PR workflow.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes