Release Troubleshooting

April 25, 2026 ยท View on GitHub

Use this guide when the release-please job does not behave as expected.

Quick Checks

  1. Confirm the push landed on main or rel/*.
  2. Confirm the release-please job actually ran in ../.github/workflows/ci.yml.
  3. Confirm the branch contains at least one releasable commit such as feat, fix, or deps.
  4. Check whether a release PR is already open.

Symptom: No Release PR Was Opened

Check these in order:

  1. The commit type may not be releasable.
  2. A release PR may already exist.
  3. The branch may not match the workflow trigger.
  4. The workflow configuration on that branch may not match the default branch.

Details:

  • feat, fix, and deps trigger release PR creation.
  • chore entries can appear in release notes, but chore alone does not trigger a release PR.
  • If you need a release from non-releasable commits only, add a commit body footer such as Release-As: 0.0.1.
  • If a prior release PR is still open, release-please usually updates that PR instead of opening a new one.

Symptom: The Workflow Fails Before Creating A Token

Check repository settings:

  1. Repository Actions variable RELEASE_PLEASE_APP_ID exists.
  2. Repository Actions secret RELEASE_PLEASE_APP_PRIVATE_KEY exists.
  3. The private key value is valid PEM content.
  4. The GitHub App is installed on this repository.

Notes:

  • Editor diagnostics may warn that the variable or secret names are unknown until they exist in repository settings.
  • That warning does not mean the workflow YAML is invalid.

Symptom: The Workflow Fails Creating The GitHub App Token

Common causes:

  1. The app ID is wrong.
  2. The private key is expired, rotated, or pasted incorrectly.
  3. The app is not installed on this repository.
  4. The installation permissions do not match the requested permissions.

Required repository permissions for this setup:

  • Contents: Read and write
  • Pull requests: Read and write
  • Issues: Read and write
  • Metadata: Read-only

If the app permissions were changed after installation, the installation may need approval again.

Symptom: A Release PR Exists, But CI Did Not Run On It

This is usually a workflow-trigger or app-installation issue rather than a release-please versioning issue. Verify:

  1. The GitHub App installation is active on this repository.
  2. The app permissions still include contents, pull requests, and issues write access.
  3. The downstream workflow itself is allowed to run on the event type created by the bot.

Symptom: A Release PR Exists, But No Release Happened After Merge

Check these items:

  1. The merge happened on main or rel/*.
  2. The post-merge push triggered ../.github/workflows/ci.yml.
  3. The workflow still has contents, issues, and pull-requests write permissions.
  4. Repository settings still allow workflows to create pull requests if your organization restricts that behavior.

Also check whether the merged PR was the release PR itself and not a normal feature PR.

Symptom: The Version Number Is Not What You Expected

Check the commit history since the last release:

  • fix produces a patch bump.
  • feat produces a minor bump.
  • breaking changes can produce a major bump.

This repo currently sets:

  • release-please-action using config-file and manifest-file for per-workspace releases under apps/*

If you need an explicit version beyond that, add Release-As: x.y.z to the commit body.

Symptom: Old History Was Reprocessed

That usually means one of these changed unexpectedly:

  1. The release tag history was changed.
  2. The repository history on the target branch changed unexpectedly.
  3. The workflow was switched and release-please is now calculating from a different previous release.

Symptom: The Changelog Looks Wrong

Check these sources in order:

  1. The merged commit subjects on the release branch.
  2. The release PR body generated by release-please.
  3. The action inputs and release behavior in ../.github/workflows/ci.yml.

Remember:

  • release-please builds notes from Conventional Commits.
  • chore may be included in notes but does not create a release by itself.
  • merged PR titles and squash-merge messages matter if squash merge is used.

When something is wrong, use this exact order:

  1. Open the latest run of ../.github/workflows/ci.yml.
  2. If the job failed before token creation, verify RELEASE_PLEASE_APP_ID, RELEASE_PLEASE_APP_PRIVATE_KEY, app installation, and app permissions.
  3. Check whether the commit set contains feat, fix, or deps.
  4. Look for an already-open release PR.
  5. Confirm the Run release-please step in ../.github/workflows/ci.yml still uses the expected direct inputs.

If all of those are correct and the workflow still does not behave as expected, inspect the workflow logs for the Run release-please step and compare the result with the current branch history.