release-please-configuration（发布请配置）

Release-Please Configuration

When to Use This Skill

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

Core Files

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:

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:

1. Missing include-component-in-tag: true at root level
2. 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

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:

1. 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"}
]

1. 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:

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

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

1. Update release-please-config.json:

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

1. Update .release-please-manifest.json:

{
  "new-package": "1.0.0"
}

1. 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:

1. Add "include-component-in-tag": true to config
2. Add "component": "package-name" to each package
3. Old tags (v1.0.0) will be ignored
4. New releases will create component-specific tags
5. 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:

1. Are there releasable commits since last release tag?
2. Do commits follow conventional format?
3. Is the package path correct in config?

Version Not Bumping

Check:

1. Commit type (feat/fix vs chore/docs)
2. Commit scope matches package path
3. 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

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