release-please

Automates the release cycle: reads Conventional Commits → opens a Release PR (bumps version + updates CHANGELOG) → merging the PR creates a GitHub Release → downstream publish workflow triggers.

Required files

release-please-config.json          # package config
.release-please-manifest.json       # current version (release-please owns this)
.github/workflows/release-please.yml

release-please-config.json

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "release-type": "python",
  "packages": {
    ".": {
      "release-type": "python",
      "package-name": "mypackage",
      "changelog-path": "CHANGELOG.md",
      "bump-minor-pre-major": true,
      "extra-files": [
        {
          "type": "toml",
          "path": "pyproject.toml",
          "jsonpath": "$.project.version"
        }
      ]
    }
  }
}

Supported release-type values: python, node, rust, go, java, simple. For node the version lives in package.json automatically — no extra-files needed.

.release-please-manifest.json

Seed with the current released version before the first run:

{ ".": "1.2.3" }

release-please updates this file on every Release PR merge. Never edit manually.

release-please.yml

name: Release Please

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    outputs:
      release_created: ${{ steps.release.outputs.release_created }}
      tag_name: ${{ steps.release.outputs.tag_name }}
    steps:
      - uses: googleapis/release-please-action@v5
        id: release
        with:
          config-file: release-please-config.json
          manifest-file: .release-please-manifest.json

Use @v5 not @v4. v4 → v5 was a breaking rename of config options.

How it works

Conventional Commit pushed to main
  → release-please opens/updates Release PR
    → human merges PR
      → GitHub Release + tag created  ← downstream publish triggers here

The Release PR contains:

• Updated CHANGELOG.md (grouped by feat/fix/chore)
• Bumped version in pyproject.toml (or package.json etc.)
• Updated .release-please-manifest.json

Semver bump rules from Conventional Commits:

Wiring a downstream publish workflow

The publish workflow must trigger on release: [published] — NOT on tag push. release-please creates a GitHub Release, which fires release: published.

on:
  release:
    types: [published]

Critical: GitHub Actions runs the workflow from the tag ref, not HEAD. If you fix publish.yml after tagging, the fix won't apply until the next release.

Common failures and fixes

Release PR never appears

1. Check the workflow ran (push to main should trigger it)
2. Verify permissions: contents: write, pull-requests: write in workflow
3. Check commits use Conventional Commits format — chore:/docs:/ci: do NOT create a Release PR, only feat: and fix: do
4. Check .release-please-manifest.json has the correct current version — if it's ahead of any tag, release-please has nothing to release

startup_failure on release-please workflow

Almost always an Actions permissions policy issue. See github-actions-permissions skill.

release-please failed: <!DOCTYPE html>

GitHub API rate limit or transient timeout during commit backfill (release-please scans up to 500 commits looking for the last release tag). Transient — re-run or wait. The Release PR is usually already created before the timeout.

Release PR bumps to wrong version (e.g. 0.6.1 instead of 0.6.0)

The manifest was seeded at 0.6.0 but no v0.6.0 tag exists on the repo. release-please sees 0.6.0 as "unreleased" and bumps past it.

Fix: create the tag manually before the first release-please run:

git tag v0.6.0 <sha>
git push origin v0.6.0

Or accept the bump — the version number is cosmetic.

Publish workflow didn't fire after Release PR merged

The release: published event is only fired by GitHub when the Release is published. release-please creates the Release automatically but occasionally the event doesn't propagate to workflows (especially bot-created releases).

Workaround — toggle draft to re-fire the event:

RELEASE_ID=$(gh api repos/OWNER/REPO/releases/latest --jq '.id')
gh api repos/OWNER/REPO/releases/$RELEASE_ID --method PATCH --field draft=true
gh api repos/OWNER/REPO/releases/$RELEASE_ID --method PATCH --field draft=false

Squash vs merge for Release PRs

Use --merge (not --squash) when merging the Release PR:

gh pr merge 22 --repo OWNER/REPO --merge

Squash changes the commit SHA that release-please uses to track the release boundary, which can confuse the next Release PR.

Version file locations by ecosystem