release-please

Overview

release-please automates versioning and releases by analyzing Conventional Commit messages:

Push conventional commits to your default branch
release-please creates/updates a Release PR with version bump and changelog
Merge the Release PR to trigger a GitHub Release
Publish step runs when a release is created (npm, PyPI, crates.io, etc.)

release-please handles version determination, changelog generation, and git tagging. You write good commit messages; it does the rest.

Commit Message Assistance

When a user asks for help writing a commit message (not setting up a pipeline):

Ask what changed — "What did you change and why?" (skip if already described)
Suggest the type — Pick from the type table below, explain why that type fits
Draft the message — Write the full commit message (header + body if needed + footers)
Confirm — Present it for the user to approve or adjust

If the change is breaking, always include a

BREAKING CHANGE:

footer explaining migration impact.

Pipeline Setup Flow

When a user wants to set up release-please, follow this interactive protocol.

.github/workflows/release.yml

(or similar) already exists, read it first, compare against the templates in

references/workflow-templates.md

, and suggest specific improvements rather than replacing it wholesale. Common improvement opportunities: missing concurrency groups, publish not gated on

release_created

, missing idempotent publish check, overly broad permissions.

Step 1: Detect Project Type

Scan the repository for package manifests:

File	Release Type
`package.json`	`node`
`pyproject.toml` / `setup.py`	`python`
`pom.xml`	`java`
`go.mod`	`go`
`Cargo.toml`	`rust`
`*.gemspec`	`ruby`
`composer.json`	`php`
`pubspec.yaml`	`dart`
`mix.exs`	`elixir`
`Chart.yaml`	`helm`

If multiple manifests exist at the root, ask which is primary. If none found, use

simple

Step 2: Ask Configuration Questions

Ask these questions (skip any already answered or obvious from context):

Is this a monorepo? (multiple packages in subdirectories)
What is the default branch? (default:
```
main
```
)
Do you need pre-release support? (manual alpha/beta/rc releases)
Where do you publish? (npm, GitHub Packages, PyPI, Maven Central, crates.io, Docker, none)
What is the current version? (check package manifest, default:
```
0.0.0
```
)

Step 3: Generate Files

Create three files based on the answers:

release-please-config.json

json

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "packages": {
    ".": {
      "release-type": "node",
      "changelog-path": "CHANGELOG.md",
      "bump-minor-pre-major": true,
      "bump-patch-for-minor-pre-major": false,
      "draft": false,
      "prerelease": false,
      "versioning": "default",
      "extra-files": []
    }
  }
}

Adjust

release-type

based on detected project type. For monorepos, add multiple entries under

packages

with

component

names.

.release-please-manifest.json

json

{
  ".": "1.0.0"
}

Set to the current released version. Use

"0.0.0"

for new projects.

.github/workflows/release.yml

For Node.js → npm public registry (most common), use this base template:

yaml

name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

concurrency:
  group: release-${{ github.ref }}
  cancel-in-progress: false

jobs:
  release-please:
    runs-on: ubuntu-latest
    outputs:
      release_created: ${{ steps.release.outputs.release_created }}
      tag_name: ${{ steps.release.outputs.tag_name }}
      version: ${{ steps.release.outputs.version }}
    steps:
      - uses: googleapis/release-please-action@v4
        id: release

  publish:
    needs: release-please
    if: needs.release-please.outputs.release_created == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

For other ecosystems, see

references/workflow-templates.md

for complete templates including:

Node.js → GitHub Packages (with idempotent publish check)
Python → PyPI (trusted publishers)
Java → Maven Central
Go (tags only, optional GoReleaser)
Rust → crates.io
Docker (build + push with semver tags)
Monorepo (per-package publish jobs)
Pre-release pattern (workflow_dispatch with version resolution)

Always customize:

Replace
```
main
```
with the actual default branch if different
Adjust Node version, Python version, Java version, etc.
Add registry-specific secrets configuration
If pre-release support is needed, use the pre-release template from
```
references/workflow-templates.md
```

Configuration Quick Reference

Option	Default	Purpose
`release-type`	—	Package ecosystem (required)
`bump-minor-pre-major`	`false`	Treat `feat` as patch when < 1.0.0
`changelog-path`	`CHANGELOG.md`	Where to write the changelog
`include-v-in-tag`	`true`	Tag as `v1.2.3` vs `1.2.3`
`separate-pull-requests`	`false`	One PR per package (monorepo)
`draft`	`false`	Create release PRs as drafts
`extra-files`	`[]`	Additional files with version strings to update
`changelog-sections`	(defaults)	Customize which types appear in changelog

Monorepo Quick Setup

json

// release-please-config.json
{
  "packages": {
    "packages/core": { "release-type": "node", "component": "core" },
    "packages/cli": { "release-type": "node", "component": "cli" }
  }
}

json

// .release-please-manifest.json
{ "packages/core": "0.0.0", "packages/cli": "0.0.0" }

Use component names as commit scopes:

feat(core): add streaming support

For full configuration options, see

references/config-options.md

Commit Message Guide

release-please reads commit messages to determine version bumps and generate changelogs. Every commit to the default branch must follow Conventional Commits.

Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Use imperative present tense: "add" not "added"
Do not capitalize the first letter of the description
Do not end with a period

Type → Version Bump

Type	Bump	Triggers Release?
`feat`	Minor	Yes
`fix`	Patch	Yes
`deps`	Patch	Yes
`refactor`	—	No
`perf`	—	No
`test`	—	No
`docs`	—	No
`style`	—	No
`chore`	—	No
`build`	—	No
`ci`	—	No

Breaking changes (any type with

BREAKING CHANGE:

footer) → Major bump.

Breaking Change Examples

feat(api)!: redesign authentication flow

BREAKING CHANGE: /auth/login now requires OAuth2 tokens instead of API keys.

refactor(database): migrate from MongoDB to PostgreSQL

BREAKING CHANGE: all database connection strings must be updated.

Special Footers

Footer	Purpose
`BREAKING CHANGE: <desc>`	Triggers major version bump
`Release-As: x.x.x`	Force a specific version number

Quick Examples

feat(booking): add search by date range endpoint
fix(auth): resolve token refresh race condition
deps: upgrade @nestjs/core to v11.0.0
test(scheduler): add unit tests for cron parser
chore: update .gitignore

No AI Co-Author Trailers

NEVER add
Co-Authored-By
trailers for AI agents in commit messages. These pollute changelogs and git history.

For the complete commit conventions reference with 15+ examples, scopes guide, and anti-patterns, see

references/commit-conventions.md

Best Practices

Squash Merges

Configure your repository to use squash merges for feature branches. This ensures each PR produces a single conventional commit, keeping the changelog clean. Set the squash commit message to use the PR title (which should be a conventional commit message).

Permissions

The GitHub Action needs

contents: write

and

pull-requests: write

at minimum. Add

packages: write

id-token: write

for publish steps as needed. Use the principle of least privilege — grant permissions per-job, not at workflow level.

Concurrency

Always set

cancel-in-progress: false

for release workflows. Canceling a release mid-way can leave partial state (tags without releases, PRs in inconsistent state).

Publish Gating

Never publish in the release-please job itself. Use a separate

publish

job gated on

release_created == 'true'

. This separates concerns and makes retries easier.

Idempotent Publish

Check if the version already exists in the registry before publishing. This prevents failures on workflow re-runs:

yaml

- name: Check if version exists
  id: check
  run: |
    PACKAGE_NAME=$(node -p "require('./package.json').name")
    VERSION=$(node -p "require('./package.json').version")
    if npm view "${PACKAGE_NAME}@${VERSION}" version 2>/dev/null; then
      echo "exists=true" >> "$GITHUB_OUTPUT"
    else
      echo "exists=false" >> "$GITHUB_OUTPUT"
    fi
- if: steps.check.outputs.exists == 'false'
  run: npm publish

Bootstrapping Existing Projects

When adding release-please to a project with existing releases:

Set
```
.release-please-manifest.json
```
to your current version
Merge the setup PR with a
```
chore:
```
commit
release-please will create the next release PR based on subsequent commits
Alternatively, use
```
Release-As: x.x.x
```
footer to force a starting version

Troubleshooting

No Release PR Created

Ensure commits since the last release include at least one releasable type (
```
feat
```
,
```
fix
```
,
```
deps
```
)
Check that commits are on the correct branch (must match workflow trigger)
Verify
```
release-please-config.json
```
and manifest exist and are valid JSON
Check Actions logs for permission errors

Wrong Version Bump

Review commit messages —
```
chore:
```
won't trigger a release,
```
feat:
```
triggers minor
Check for
```
BREAKING CHANGE:
```
footers that may trigger an unexpected major bump
Use
```
Release-As: x.x.x
```
footer to override if needed

Pre-Release Flow

Pre-releases use
```
workflow_dispatch
```
, not automatic push triggers
The pre-release identifier is appended to the current version:
```
1.2.3-alpha.1
```
Use the
```
next
```
npm tag (or equivalent) for pre-releases,
```
latest
```
for stable
See the pre-release template in
```
references/workflow-templates.md
```

Token / Permission Issues

Default
```
GITHUB_TOKEN
```
works for release-please PRs and releases
Publishing to external registries requires dedicated secrets (
```
NPM_TOKEN
```
, etc.)
GitHub Packages publishing uses
```
GITHUB_TOKEN
```
with
```
packages: write
```
permission
For PyPI, use trusted publishers instead of API tokens

References

Reference	Description
`references/commit-conventions.md`	Full Conventional Commits specification with examples and anti-patterns
`references/workflow-templates.md`	Complete workflow templates for 9 ecosystems
`references/config-options.md`	All configuration options, release types, and Action inputs/outputs
release-please GitHub	Official documentation
Conventional Commits	Specification

release-please

NPX Install

Tags

SKILL.md Content

release-please

Overview

Commit Message Assistance

Pipeline Setup Flow

Step 1: Detect Project Type

Step 2: Ask Configuration Questions

Step 3: Generate Files

release-please-config.json

.release-please-manifest.json

.github/workflows/release.yml

Configuration Quick Reference

Monorepo Quick Setup

Commit Message Guide

Format

Type → Version Bump

Breaking Change Examples

Special Footers

Quick Examples

No AI Co-Author Trailers

Best Practices

Squash Merges

Permissions

Concurrency

Publish Gating

Idempotent Publish

Bootstrapping Existing Projects

Troubleshooting

No Release PR Created

Wrong Version Bump

Pre-Release Flow

Token / Permission Issues

References