Release-Please Configuration

Expert knowledge for configuring Google's release-please for automated releases.

Core Files

File Purpose

release-please-config.json

Package configuration, changelog sections, extra-files

.release-please-manifest.json

Current versions for each package

.github/workflows/release-please.yml

GitHub Actions workflow

Monorepo Configuration

Critical Settings for Monorepos

{ "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", "include-component-in-tag": true, "separate-pull-requests": true, "packages": { "package-a": { "component": "package-a", "release-type": "simple", "extra-files": ["package-a/version.json"] } } }

Key Fields:

Field Required Purpose

include-component-in-tag

Yes (monorepo) Creates package-a-v1.0.0 tags instead of v1.0.0

component

Yes (monorepo) Unique identifier for each package; must be set for every package

separate-pull-requests

Recommended Creates per-package release PRs instead of combined

Common Failure: Duplicate Release Tags

Symptom: Workflow fails with Duplicate release tag: v2.0.0

Cause: All packages try to create the same tag (e.g., v2.0.0 ) because:

• Missing include-component-in-tag: true at root level

• Missing component field in each package

Fix:

{ "include-component-in-tag": true, "packages": { "my-package": { "component": "my-package", // Add this to every package ... } } }

Common Failure: Multiple Paths Warning

Symptom: Multiple paths for : package-a, package-b

Cause: Empty component field (the : with nothing after it indicates empty string)

Fix: Ensure every package has "component": "package-name" set

Release Types

Type Use Case Version File

simple

Generic projects version.txt

node

npm packages package.json

python

Python (pyproject.toml) pyproject.toml

rust

Rust crates Cargo.toml

go

Go modules version.go or similar

Extra Files for Custom Version Locations

For JSON files, you must use the object format with type , path , and jsonpath :

{ "packages": { "my-plugin": { "release-type": "simple", "extra-files": [ {"type": "json", "path": "my-plugin/.claude-plugin/plugin.json", "jsonpath": "$.version"} ] } } }

Common Mistakes:

• Using a simple string path for JSON files:

// WRONG - won't update the version field "extra-files": [".claude-plugin/plugin.json"]

// CORRECT - uses JSON updater with jsonpath "extra-files": [ {"type": "json", "path": ".claude-plugin/plugin.json", "jsonpath": "$.version"} ]

• Using absolute paths instead of package-relative paths:

// WRONG - path gets doubled (package-name/package-name/.claude-plugin/...) "extra-files": [ {"type": "json", "path": "my-plugin/.claude-plugin/plugin.json", "jsonpath": "$.version"} ]

// CORRECT - path is relative to the package directory "extra-files": [ {"type": "json", "path": ".claude-plugin/plugin.json", "jsonpath": "$.version"} ]

Key insight: For monorepo packages, extra-files paths are relative to the package directory, NOT the repo root. Release-please automatically prepends the package path.

File Type Formats:

File Type Format

JSON {"type": "json", "path": "...", "jsonpath": "$.version"}

YAML {"type": "yaml", "path": "...", "jsonpath": "$.version"}

TOML {"type": "toml", "path": "...", "jsonpath": "$.version"}

XML {"type": "xml", "path": "...", "xpath": "//version"}

Plain text "path/to/version.txt" (string is fine)

Changelog Configuration

Standard Changelog Sections

{ "changelog-sections": [ {"type": "feat", "section": "Features"}, {"type": "fix", "section": "Bug Fixes"}, {"type": "perf", "section": "Performance"}, {"type": "refactor", "section": "Code Refactoring"}, {"type": "docs", "section": "Documentation"} ] }

Commit Type to Version Bump

Commit Type Version Bump CHANGELOG Section

feat:

Minor Features

fix:

Patch Bug Fixes

feat!:

Major Features (with BREAKING CHANGE)

BREAKING CHANGE:

Major Breaking Changes

chore:

None (hidden)

docs:

None Documentation

refactor:

None Code Refactoring

perf:

Patch Performance

Manifest File

The .release-please-manifest.json tracks current versions:

{ "package-a": "1.2.3", "package-b": "2.0.0" }

Important: This file is auto-updated by release-please. Manual edits should only be done for:

• Initial bootstrapping

• Resetting after tag migration

GitHub Actions Workflow

Minimal Workflow

name: Release Please

on: push: branches: - main

permissions: contents: write pull-requests: write

jobs: release-please: runs-on: ubuntu-latest steps: - uses: googleapis/release-please-action@v4 with: token: ${{ secrets.GITHUB_TOKEN }}

With Custom Token (Required for Triggering Other Workflows)

• uses: googleapis/release-please-action@v4 with: token: ${{ secrets.MY_RELEASE_PLEASE_TOKEN }}

Use a PAT if you need release PRs to trigger other workflows (e.g., CI checks).

Adding a New Package to Monorepo

• Update release-please-config.json :

{ "packages": { "new-package": { "component": "new-package", "release-type": "simple", "extra-files": ["new-package/.version-file.json"], "changelog-sections": [...] } } }

• Update .release-please-manifest.json :

{ "new-package": "1.0.0" }

• Create initial version file in the package if needed.

Migrating from Shared Tags to Component Tags

When transitioning from v1.0.0 style tags to component-v1.0.0 :

• Add "include-component-in-tag": true to config

• Add "component": "package-name" to each package

• Old tags (v1.0.0 ) will be ignored

• New releases will create component-specific tags

• Close any pending combined release PRs

Note: Release-please will scan for component-specific tags. First run after migration will create release PRs for all packages with changes since the manifest version.

Troubleshooting

Workflow Succeeds but No PR Created

Check:

• Are there releasable commits since last release tag?

• Do commits follow conventional format?

• Is the package path correct in config?

Version Not Bumping

Check:

• Commit type (feat/fix vs chore/docs)

• Commit scope matches package path

• Conventional commit format is correct

Wrong Version in Extra Files

Ensure extra-files paths are correct relative to repo root, not package root:

// Correct "extra-files": ["my-package/.claude-plugin/plugin.json"]

// Wrong (if package path is "my-package") "extra-files": [".claude-plugin/plugin.json"]

Quick Reference

Conventional Commit Format

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

[optional body]

[optional footer(s)]

Examples:

feat(auth): add OAuth2 support fix(api): handle timeout edge case feat(cli)!: redesign command interface

BREAKING CHANGE: Commands now use subcommand syntax.

Version Bump Rules

Pattern Bump

feat:

Minor (1.0.0 → 1.1.0)

fix:

Patch (1.0.0 → 1.0.1)

! suffix or BREAKING CHANGE:

Major (1.0.0 → 2.0.0)

chore: , docs: , style: , test:

No bump

Useful Commands

Check latest release-please-action version

curl -s https://api.github.com/repos/googleapis/release-please-action/releases/latest | jq -r '.tag_name'

List pending release PRs

gh pr list --label "autorelease: pending"

View recent workflow runs

gh run list --workflow=release-please.yml --limit=5

Check failed workflow logs

gh run view <run-id> --log-failed

Resources

• Release-Please Documentation

• Release-Please Action

• Conventional Commits

• Manifest Releaser Guide