Release Please — Automated Releases Based on Conventional Commits

Introduction

Release Please reads your commit history, groups Conventional Commit messages by type, and opens a release PR that bumps the version and updates the CHANGELOG. When you merge the PR it creates a GitHub Release with the generated notes, removing manual versioning from your workflow.

What Release Please Does

• Parses Conventional Commit messages (feat, fix, chore, etc.) since the last release
• Generates a CHANGELOG.md entry and bumps the version following semver rules
• Opens a release pull request that accumulates unreleased changes
• Creates a GitHub Release and git tag when the release PR is merged
• Supports monorepos with per-package versioning and linked releases

Architecture Overview

Release Please runs as a Node.js CLI or GitHub Action. It reads the git log from the last release tag, classifies commits by Conventional Commit type, and determines the appropriate semver bump. A strategy plugin system handles language-specific version files (package.json, setup.py, pom.xml, Cargo.toml). The release PR is kept up to date on each push to the default branch.

Self-Hosting & Configuration

• Most teams use the googleapis/release-please-action GitHub Action with minimal YAML config
• release-please-config.json at the repo root defines release type, packages, and changelog sections
• .release-please-manifest.json tracks current versions for each package in a monorepo
• Supports 20+ release types: node, python, java, go, rust, ruby, helm, terraform-module, and more
• Custom changelog sections and commit grouping can be configured per repository

Key Features

• Zero-touch versioning driven entirely by commit message conventions
• Monorepo support with independent or linked package releases
• Language-aware version bumping across package.json, pyproject.toml, Cargo.toml, and others
• Automatically generated CHANGELOG with grouped commit entries
• GitHub Release creation with release notes and tag management

Comparison with Similar Tools

• semantic-release — Similar commit-driven releases but publishes immediately on merge; less visibility into upcoming changes
• Changesets — Manual changeset files per PR; more explicit but requires developer discipline
• GoReleaser — Go-specific release automation with cross-compilation and artifact publishing
• Standard Version — Deprecated predecessor; Release Please is the recommended migration path
• Lerna — Monorepo tool with versioning support but broader scope and heavier configuration

FAQ

Q: Does Release Please require Conventional Commits? A: Yes. It relies on commit prefixes (feat:, fix:, etc.) to determine version bumps and generate changelog entries.

Q: Can I use Release Please outside of GitHub? A: The CLI can run against any Git repository, but the automated PR and release flow is tightly integrated with GitHub.

Q: How does monorepo support work? A: You define packages in release-please-config.json with their paths and release types. Each package gets its own version, PR section, and tag.

Q: What happens if I push multiple features before merging the release PR? A: Release Please updates the same open PR, accumulating all changes and recalculating the version bump.

Sources

• https://github.com/googleapis/release-please
• https://github.com/googleapis/release-please-action