# googleapis/release-please-action: Release PRs Driven by Commit Messages > A GitHub Action that reads Conventional Commits and opens a pull request holding the version bump and changelog. It fits single-package repos with disciplined commit hygiene, and it is the wrong tool when your history has none. **googleapis/release-please-action** — automated releases based on conventional commits - Repository: https://github.com/googleapis/release-please-action - Stars: 2,538 · Forks: 329 - Language: TypeScript - License: Apache-2.0 - Published: 2026-09-28 · Updated: 2026-09-28 · Language: en - Canonical page: https://hysenlabs.com/projects/googleapis-release-please-action ## What release-please-action actually decides for you The action does not build, test or publish anything. It reads commit messages that follow the Conventional Commits specification, works out the next semantic version, and opens (or updates) a pull request containing that version bump and a generated changelog. Merging that pull request is what produces the release. The audience is maintainers of repositories where releases are tags plus changelog entries, and where commit messages are already written in a machine-readable form. If your release process involves uploading binaries, publishing to a package registry or running a deploy step, this action is only the first half of it. The README frames the whole thing as automation of releases from commit messages, and that is the boundary of its responsibility. ## The release PR loop, from commit to tag The mechanism is a loop rather than a single run. A push to the configured branch triggers the workflow. The action parses the commits since the last release, decides the next version, and opens a release pull request. That PR carries the version bump in the relevant manifest file and the changelog additions. While it stays open, further commits to the branch are folded into it, so the PR is continuously updated rather than duplicated. When a maintainer merges it, the action creates the tag and the GitHub release. The README notes that a release-type input is the most straightforward configuration but allows no further customization; anything beyond that requires a manifest config. That is the real fork in the road: one input for a simple repository, or a config file plus a versions manifest for anything more structured. The action itself is a TypeScript wrapper around the release-please library, built with ncc into dist/ and pinned to Node 20 or newer according to package.json. ## Installing the action and getting a first release PR There is no package to install. You add a workflow file to the repository. The README gives this as the basic configuration: create .github/workflows/release-please.yml with the contents below. The permissions block matters, because the action writes releases, issues and pull requests. ```yaml on: push: branches: - main permissions: contents: write issues: write pull-requests: write name: release-please jobs: release-please: runs-on: ubuntu-latest steps: - uses: googleapis/release-please-action@v4 with: token: ${{ secrets.MY_RELEASE_PLEASE_TOKEN }} release-type: simple ``` The token secret name is arbitrary, as the README comments note; what matters is that the secret exists and holds a personal access token. After merging the workflow, commits that follow the Conventional Commits convention will start producing release pull requests. Expect a PR to appear on the next qualifying push, not a release tag: the tag comes when you merge that PR. For a repository that needs more than one release strategy, the README points to a manifest config and this action configuration: ```yaml steps: - uses: googleapis/release-please-action@v4 with: token: ${{ secrets.MY_RELEASE_PLEASE_TOKEN }} config-file: release-please-config.json manifest-file: .release-please-manifest.json ``` Both paths are optional inputs with those same defaults, so passing them explicitly only matters when you have moved the files. ## The token problem that catches most first-time users The action defaults to secrets.GITHUB_TOKEN, and the README carries a warning about it. Resources created with that token do not trigger further workflow runs, and workflows normally triggered by release.created events will not run either. GitHub's own documentation, quoted in the README, explains the reason: events triggered by GITHUB_TOKEN do not create a new workflow run, to prevent recursive runs. The practical consequence is that a release created by this action will not kick off your publish or deploy workflow. The documented workaround is to supply a personal access token through the token input. This is the single most common source of confusion with the action, and it is a GitHub Actions property rather than a defect in release-please. If you skip the PAT, everything looks correct and nothing downstream fires. ## Where the action stops being the right tool The action assumes Conventional Commits. A repository with free-form commit messages gets nothing useful out of it: no version bump can be inferred, so no release PR appears. That is not a configuration problem you can tune away. The versioning-strategy input defaults to default and can be changed, but no strategy can extract a semantic version from a message that does not encode one. There is also a structural limit in the release flow itself. The release requires a human to merge a pull request, which is deliberate and is the point of the design, but it means the action is unsuitable if you want every merge to main to become a release immediately. The skip-github-release and skip-github-pull-request inputs exist for splitting tagging from PR creation, which the README describes as useful when those two steps need to happen separately, but they do not remove the approval step. Finally, the action is GitHub-specific. The README documents github-api-url and github-graphql-url overrides, which are aimed at GitHub Enterprise style endpoints, not at other forges. ## release-please-action versus a tag-and-changelog toolchain The nearest alternative in the same problem space is release-plz, which the search data pairs with release-please directly. The difference in approach is the ecosystem: release-plz is built for Rust and works from Cargo manifests and Cargo.toml versions, while release-please-action is language-agnostic and infers versions from commit messages against a release-type or a manifest config. If your repository is a Rust workspace, release-plz reads the versions you already maintain in the manifest. If your repository is polyglot or the version lives only in a release-type strategy, release-please's model fits better. The other common alternative is not a tool at all: a manual tag plus a hand-written changelog, or a changelog generator that produces notes without opening a release PR. Those give you a release on demand with no approval loop, at the cost of doing the version arithmetic yourself. The trade the action makes is explicit: it takes over version inference and changelog assembly, and in exchange it inserts a pull request into your release path. ## Maintenance, version pinning and licence The repository is not archived, and the last push was on 2026-08-28. The most recent release is v5.0.0 from 2026-04-22, following v4.4.1 and v4.4.0. The README's examples still reference the v4 tag while the package version is 5.0.0, so pinning to a major tag is a decision you should make deliberately rather than by copying the snippet. Upgrading across a major version means reading the release notes for that tag, since the README does not document rollback or a migration path between majors. The licence is Apache-2.0, which permits commercial and private use and requires that you preserve the licence and notice files; the repository ships a LICENSE file and a SECURITY.md. This is a general description of the licence terms, not legal advice, and if the action is embedded in a distributed product you should have your own counsel read the terms. The runtime requirement is Node 20 or newer according to package.json, which matters if you build the action from source rather than consuming a released tag. ## Conclusion Adopt it if your repository already writes Conventional Commits and you want version numbers and changelogs to come out of the commit history rather than a manual edit. Skip it if your team writes free-form messages, if you need a release on every merge rather than a human-approved pull request, or if your release process is not tied to a Git tag. Before wiring it in, verify two things: that the workflow grants contents, issues and pull-requests write permission, and that you have a personal access token if you expect other workflows to run on the releases and PRs it creates. The default GITHUB_TOKEN will not trigger them. ## FAQ ### What does release-please-action do? It reads Conventional Commit messages, determines the next version, and opens a pull request with the version bump and changelog. Merging that pull request creates the tag and the GitHub release. ### What is the difference between release-please-action and release-plz? release-plz works from Rust Cargo manifests and their versions, while release-please-action is language-agnostic and infers the version from commit messages using a release-type or a manifest config. The choice mostly follows whether your version already lives in a Rust manifest. ### What are some alternatives to release-please-action? release-plz is the closest tool in the same space, and it differs by reading Rust manifests instead of commit messages. The other option is a manual tag with a hand-written changelog, which releases on demand but leaves the version arithmetic to you. ## Sources - [googleapis/release-please-action on GitHub](https://github.com/googleapis/release-please-action) - [Issues](https://github.com/googleapis/release-please-action/issues) - [License: Apache-2.0](https://github.com/googleapis/release-please-action/blob/main/LICENSE) - [README](https://github.com/googleapis/release-please-action/blob/main/README.md) - [Releases](https://github.com/googleapis/release-please-action/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/googleapis-release-please-action