Release Please

Release-Please Setup

Configures release-please in a project for automated version bumping, changelog generation, GitHub releases, and optional registry publishing.

Before You Start

Always fetch current documentation before configuring release-please. The action and config schema evolve across versions.

| Resource | URL | | ---------------------------- | -------------------------------------------------------------------------------- | | release-please-action README | https://github.com/googleapis/release-please-action | | Config schema reference | https://github.com/googleapis/release-please/blob/main/docs/manifest-releaser.md | | Supported release types | https://github.com/googleapis/release-please/blob/main/docs/customizing.md |

Use WebFetch on these URLs to get current documentation before proceeding.

Action version pin: @v5 (Apr 2026) and @v4 are both actively maintained. v5 only changes the runner runtime from Node 20 to Node 24 — no input/output changes. v4 still receives library bumps and is the safer pin for self-hosted runners that haven't upgraded to Node 24. Avoid @v3 — it's deprecated and uses a different output shape (release_created singular instead of releases_created plural).

Library version: release-please-action v5.0.0 bundles release-please library v17.6.0. Upstream ships releases roughly weekly to biweekly — the library was at v17.11.1 as of 2026-07-31, several minor versions ahead of what v5.0.0 bundles (source: release-please releases, npm registry). Check the action's own package-lock.json at your pinned tag if you need the exact bundled version.

Quick Start

1. Detect project type (package.json, deno.json, Cargo.toml, pyproject.toml, etc.)
2. Check for existing release workflows in .github/workflows/
3. Create release-please config files at project root
4. Create or update the release workflow (single workflow containing release + publish jobs)
5. Verify the project uses conventional commits (check git log)

Detailed Workflow

Step 1: Detect Project Type and Registry

Read the project's manifest file to determine:

• Language/ecosystem: Node (npm), Deno (JSR), Rust (crates.io), Python (PyPI), Go, etc.
• Package name: From the manifest (package.json name, deno.json name, etc.)
• Current version: From the manifest
• Monorepo or single package: Check for workspaces, multiple package dirs

Map to the correct release-type:

| Ecosystem | release-type | Version file | | ------------- | ------------ | ----------------------------------------------- | | Node.js (npm) | node | package.json | | Deno (JSR) | node | Use extra-files with jsonpath for deno.json | | Rust | rust | Cargo.toml | | Python | python | pyproject.toml or setup.py | | Go | go | No version file (tag-based) | | Simple/other | simple | version.txt |

For Deno/JSR projects, use release-type: node with extra-files to update deno.json:

{
  "extra-files": [{ "type": "json", "path": "deno.json", "jsonpath": "$.version" }]
}

Pre-1.0 projects: add "bump-minor-pre-major": true so feat: bumps minor (0.2.0 -> 0.3.0) and fix: bumps patch. Without this, 0.x projects stay flat because feat-to-minor only applies at >= 1.0.

Step 2: Check Existing Workflows

Read .github/workflows/ for existing publish/release workflows. Common patterns:

• Publish on push to main: Should be changed to publish conditionally via release-please.
• Publish on release event: Can be kept as a manual fallback, but will not auto-fire from release-please (see Gotchas).
• No existing workflow: Create a single release workflow with both jobs.

Step 3: Create Config Files

release-please-config.json (project root):

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "packages": {
    ".": {
      "package-name": "",
      "release-type": "",
      "extra-files": []
    }
  }
}

For monorepos, add each package under packages with its relative path as the key. See [references/monorepo.md](references/monorepo.md).

.release-please-manifest.json (project root):

{ ".": "" }

Bootstrap with the current version from the project manifest. For projects with pre-existing history that doesn't match release-please's expectations, see [references/first-release-bootstrap.md](references/first-release-bootstrap.md).

Step 4: Create GitHub Actions Workflow

The publish job MUST live in the same workflow file as release-please. A separate workflow triggered by on: release will not fire because GitHub prevents GITHUB_TOKEN-created events from triggering other workflows.

name: Release Please

on:
  push:
    branches:
      - main

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

jobs:
  release-please:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
    outputs:
      releases_created: ${{ steps.release.outputs.releases_created }}
      tag_name: ${{ steps.release.outputs.tag_name }}
    steps:
      - uses: googleapis/release-please-action@v4
        id: release
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

  publish:
    needs: release-please
    if: ${{ needs.release-please.outputs.releases_created == 'true' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write # Required for OIDC (npm provenance, JSR)
    steps:
      - uses: actions/checkout@v4
      # Add setup, quality checks, and publish steps here

Step 5: Add CI Workflow for PRs

Release-please PRs created with GITHUB_TOKEN do not trigger pull_request workflows automatically. A CI workflow on PRs is still valuable for human-authored PRs:

name: CI

on:
  pull_request:
    branches:
      - main

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Add linting, type checking, test steps

Because release PRs skip this workflow, repeat the same quality checks inside the publish job before the actual publish step.

Step 6: Handle Formatter Conflicts

Release-please generates CHANGELOG.md with its own formatting (e.g., * for list markers). If the project uses a formatter that enforces different conventions, exclude CHANGELOG.md from formatting:

• Deno: Add "exclude": ["CHANGELOG.md"] to the fmt section in deno.json
• Prettier: Add CHANGELOG.md to .prettierignore
• ESLint: Add CHANGELOG.md to .eslintignore or ignorePatterns

Step 7: Update Existing Publish Workflows

If the project has an existing publish workflow triggered on push: main:

1. Remove the push trigger (publishing now runs inside the release workflow).
2. Optionally keep release: types: [published] as a manual fallback (it will not auto-fire from release-please, but works for gh release create).

Common Patterns

OIDC-Authenticated Publishing

JSR supports OIDC out of the box. npm requires enabling Trusted Publishing (GA 2025-07-31) per-package on npmjs.com first — linking the org/repo/workflow filename — plus npm CLI >= 11.5.1 and Node.js >= 22.14.0 in the runner. Once configured, a plain npm publish authenticates via OIDC and attaches provenance automatically; --provenance alone does not replace the need for a token without Trusted Publishing configured, since it only adds a build attestation, not authentication. Skip long-lived API tokens entirely once set up:

permissions:
  contents: read
  id-token: write
steps:
  - uses: actions/checkout@v4
  # npm with Trusted Publishing configured on npmjs.com:
  - run: npm publish --access public
  # OR JSR:
  - run: deno publish

No NPM_TOKEN or JSR auth secret required. See [references/token-strategy.md](references/token-strategy.md) for when OIDC is insufficient.

Syncing Version Across Multiple Files

Use extra-files with jsonpath to keep version in sync across deno.json, plugin manifests, README badges, etc:

{
  "extra-files": [
    { "type": "json", "path": "deno.json", "jsonpath": "$.version" },
    { "type": "json", "path": "plugin.json", "jsonpath": "$.version" },
    { "type": "json", "path": "plugin.json", "jsonpath": "$.mcpServers[*].version" }
  ]
}

Supported types: json, yaml, toml, generic (regex-based). See manifest-releaser.md for full syntax.

Floating Major-Version Tag

Consumers of reusable GitHub Actions often pin to @v1. Maintain a floating major tag with a post-release job:

major-tag:
  needs: release-please
  if: ${{ needs.release-please.outputs.releases_created == 'true' }}
  runs-on: ubuntu-latest
  permissions:
    contents: write
  steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0
    - name: Update major version tag
      env:
        TAG: ${{ needs.release-please.outputs.tag_name }}
      run: |
        MAJOR=$(echo "$TAG" | sed -E 's/^v?([0-9]+).*/v\1/')
        git tag -f "$MAJOR" "$TAG"
        git push origin "$MAJOR" --force

Concurrency Control

Prevent overlapping release runs when multiple commits land in quick succession:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false # Let in-flight releases finish rather than kill them

Downstream Post-Release Updates

Common need: after release, update a Homebrew tap, docs site, catalog, Docker Hub, etc. See [references/downstream-updates.md](references/downstream-updates.md) for the general pattern. Short version: GITHUB_TOKEN cannot cross repo boundaries; use a PAT or GitHub App token.

Binary Release Artifacts

For projects that ship compiled binaries (Go, Rust, Deno compile, Bun compile), see [references/binary-artifacts.md](references/binary-artifacts.md) for the multi-target build + checksum + release upload pattern.

Manual Overrides

Day-to-day, you'll often need to force a version bump, skip a release, or recover from a stuck release pipeline. Release-please supports several override mechanisms — pick the most local one for the job.

Force a specific version

Via commit footer (most common, no config change):

chore: release 2.0.0

Release-As: 2.0.0

Or as an empty commit:

git commit --allow-empty -m "chore: release 2.0.0" -m "Release-As: 2.0.0"
git push

The footer is case-insensitive (Release-As: / release-as:). When present, release-please uses the footer value instead of computing a bump from commits.

Via config field (sticky until removed):

{ "packages": { ".": { "release-as": "2.0.0" } } }

Remove release-as after the release is cut, or every subsequent PR keeps forcing 2.0.0.

Via action input (added in release-please-action@v4.4.0):

- uses: googleapis/release-please-action@v4
  with:
    release-as: 2.0.0

Useful when paired with workflow_dispatch for ad-hoc releases triggered from the GitHub UI.

Force a bump direction (always-bump-\*)

versioning-strategy overrides Conventional Commits parsing entirely. Set in config or as an action input (action input added in v4.4.0):

| Strategy | Effect | | ------------------- | ---------------------------------------------------------------- | | default | Conventional Commits (feat -> minor, fix -> patch, ! -> major) | | always-bump-patch | Every release is a patch bump | | always-bump-minor | Every release is a minor bump | | always-bump-major | Every release is a major bump | | service-pack | Increments the patch suffix (for service-pack release lines) | | prerelease | Bumps the prerelease identifier |

Force a major bump from a single commit

Use ! after the type, or add a BREAKING CHANGE: (or BREAKING-CHANGE:) footer:

feat!: rename `foo` to `bar`

Or:

feat: rename `foo` to `bar`

BREAKING CHANGE: `foo` is now `bar`

For pre-1.0 projects, breaking changes still only bump minor by default. Set "bump-patch-for-minor-pre-major": true to instead bump patch on breaking changes pre-1.0.

Force release-please to re-run

If a release PR didn't open after qualifying commits, or didn't tag after merge, apply the release-please:force-run label to the merged release PR (or the latest merged PR with qualifying commits). Release-please picks this up on its next workflow run and reprocesses the release. This is the canonical fix for "release PR stale" and "tag workflow didn't fire" states.

You can also push an empty commit to kick the workflow:

git commit --allow-empty -m "chore: trigger release-please"
git push

Skip a release

• Per-commit: use a non-releasable type (chore:, docs:, ci:, style:, test:, refactor:, build:). These are excluded from version bumps by default.
• Per-workflow run: set skip-github-release: true and/or skip-github-pull-request: true on the action.
• Skip changelog only (cut the release tag, don't touch CHANGELOG): "skip-changelog": true in config (release-please v17.1+).

Skip CI labeling

Set skip-labeling: true on the action (added in v4.2.0) if branch protection rules or repo policies make the auto-applied labels (autorelease: pending, autorelease: tagged) inconvenient. The state machine still works because release-please reads commit + PR metadata too, but recovery via the force-run label still expects labels to be writable.

Prereleases

Alpha, beta, rc, and custom prerelease identifiers are a dedicated topic. See [references/prereleases.md](references/prereleases.md).

Troubleshooting

The single most useful debugging signal is the PR label: autorelease: pending vs autorelease: tagged. Pending means the release PR exists and is awaiting merge. Tagged means the release has been cut (post-merge state).

| Symptom | Likely cause | Fix | | --------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | No release PR created | No qualifying commits since last release (all docs:/chore:/ci:) | Check git log since last tag. Add a feat: or fix:. | | No release PR despite qualifying commits | Branch protection blocks GITHUB_TOKEN PRs | Allow Actions to open PRs in repo settings (Settings > Actions > General). | | Release PR stale / state machine stuck | Race or transient API failure left release-please mid-state | Apply the release-please:force-run label to the merged release PR, then re-run the workflow. | | Tag wasn't cre

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wyattjoh
• Source: wyattjoh/skills
• License: MIT

Install and usage instructions live in the source repository linked above.