Release-Please Configuration Skill

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

Agent Skills: Release-Please Configuration

Install this agent skill to your local

Skill Files