Release Please Skill | Agent Skills

Release Please

Lean operating guide for googleapis/release-please + googleapis/release-please-action.

Use this file for mode selection, quick setup, and guardrails. Use references for full examples, output contracts, and troubleshooting detail.

When to Use

Use this skill when you need:

Conventional Commit-driven version bumps and changelog generation
Automated Release PR creation and GitHub release tagging
Single-package or monorepo/manifest release orchestration
Migration off manual tags/changelog/version workflows

Choose a Mode

Single-package mode: one version stream from repo root.
Manifest mode: independent versions per path/package.

If you have more than one independently-versioned package, use manifest mode.

Manifest Identity Model

Keep these fields separate:

packages object key: repository-relative package path used for file discovery, manifest versions, and action output prefixes.
component: stable human-facing release identity and default tag prefix.
package-name: release-strategy package identity; many strategies discover it from package.json, Cargo.toml, or equivalent.
include-component-in-tag: whether tags include the component prefix; keep enabled for independently-versioned monorepo packages.

Example:

"packages/my-module": {
  "component": "my-module",
  "release-type": "node"
}

The package key stays packages/my-module; the default tag becomes my-module-v1.2.3.

Prerequisites (Quick)

Conventional Commits in default branch history (fix:, feat:, !/BREAKING)
Branch/workflow permissions sufficient for PR + release writes
Workflow trigger on your default release branch (main/master)

Recommended minimum workflow permissions:

contents: write
pull-requests: write
issues: write (optional but commonly useful)

Quick Start

A) Single-package (minimal)

Create .github/workflows/release-please.yml with googleapis/release-please-action@v4 on push to default branch.

B) Manifest mode

Add:

release-please-config.json
.release-please-manifest.json
workflow passing config-file + manifest-file

Lifecycle

Merge Conventional Commit PRs.
Release Please opens/updates the Release PR.
CI validates release PR.
Merge release PR.
Action creates tag + GitHub Release.

Migration from Manual Releases

Stop manual changelog/tag edits on release-managed branch.
Seed manifest versions to currently released versions (manifest mode).
Choose stable component names before first managed release.
If changing an existing component name, plan tag-history migration; Release Please searches tags using the configured component.
Merge first Release PR and validate output shape usage in downstream workflow steps.

Common Failure Patterns (Summary)

No release PR: no releasable commits, wrong branch trigger, stale autorelease labels, or token/permission mismatch
Wrong bump: commit semantics mismatch with Conventional Commit expectations
Missing changelog entries: non-conventional squash titles/commit history
Manifest mismatch: package path keys don’t match actual directories
Release history not found: component changed but existing tags still use the old prefix
Workflow chain not firing: using GITHUB_TOKEN when downstream workflows require PAT/App token behavior

Guardrails

Enforce Conventional Commit linting in CI.
Keep release ownership explicit (who merges release PRs).
In monorepos, add package paths incrementally and assign stable, unique components.
Treat component renames as release migrations, not cosmetic config edits.
Avoid manual tags/changelog edits in release-managed paths.
Keep release PRs small and predictable.

Quick Verification Checklist

[ ] Workflow triggers on push to tracked branch
[ ] Permissions are explicitly set
[ ] Release PR appears after releasable commit
[ ] Merge creates expected component-prefixed tag and GitHub release
[ ] Manifest keys remain real repository paths
[ ] Downstream steps use path-prefixed action outputs, not component-prefixed output keys

Agent Skills: Release Please

Install this agent skill to your local

Skill Files