Release Troubleshooting Guide

February 5, 2026 ยท View on GitHub

This guide helps you resolve common issues with the release-please automation and npm publishing.

Table of Contents

Understanding the Release Process

The release process uses release-please to automate releases:

  1. Automated PR Creation: When commits are pushed to main, release-please analyzes conventional commits and creates/updates a release PR
  2. Release Creation: When the release PR is merged, release-please:
    • Creates a GitHub release with the new version tag
    • Updates CHANGELOG.md, package.json, and .github/release-please-manifest.json
  3. npm Publishing: After a release is created, the workflow automatically:
    • Checks out the tagged version
    • Installs dependencies
    • Builds the package
    • Publishes to npm using NPM Trusted Publishers with provenance (no NPM_TOKEN needed)

Common Issues

Failed npm Publish

Symptom: GitHub release exists, but the package is not on npm.

Cause: The npm publish step failed (e.g., OIDC authentication error, network issue, npm downtime, or GitHub Actions permissions issue).

How to verify:

# Check if version exists on npm
npm view @tiberriver256/mcp-server-azure-devops@0.1.44

# Check latest version
npm view @tiberriver256/mcp-server-azure-devops version

Solution: Re-publish the existing release

Release Already Exists

Symptom: Trying to re-run the workflow, but all publish steps are skipped.

Cause: Release-please tracks state via the manifest file (.github/release-please-manifest.json). If the version in the manifest matches package.json, it considers the release complete and doesn't set release_created=true.

Solution: Re-publish the existing release or Force a new release

Manual Release Needed

Symptom: Need to publish a hotfix or re-release immediately.

Solution: Re-publish the existing release

Solutions

Re-publishing an Existing Release

Use this when a GitHub release exists but npm publish failed. This will publish the existing tagged version to npm without creating a new release.

Steps:

  1. Go to the Actions tab in GitHub
  2. Click "Run workflow" dropdown (you'll see this on the right side)
  3. Enter the full git tag in the "tag" field (e.g., mcp-server-azure-devops-v0.1.44)
  4. Click "Run workflow"

What this does:

  • Checks out the exact code from that tag
  • Builds the package
  • Publishes to npm
  • Does NOT create a new GitHub release
  • Does NOT modify version files or CHANGELOG

Example:

Tag: mcp-server-azure-devops-v0.1.44

Force a New Release

Use this when you need to create a completely new release (incrementing the version number).

Option 1: Let release-please handle it (Recommended)

  1. Make a new commit with conventional commit format:

    git commit --allow-empty -m "chore: trigger new release"
git push origin main

  2. Release-please will create a new release PR

  3. Merge the PR to trigger the release

Option 2: Manual version bump

  1. Update version in package.json:

    npm version patch  # for 0.1.44 -> 0.1.45
# or
npm version minor  # for 0.1.44 -> 0.2.0
# or
npm version major  # for 0.1.44 -> 1.0.0

  2. Update .github/release-please-manifest.json to match the new version

  3. Update CHANGELOG.md with the new version section

  4. Commit and push:

    git add package.json package-lock.json .github/release-please-manifest.json CHANGELOG.md
git commit -m "chore: release v0.1.45"
git push origin main

  5. Create a tag and release manually:

    git tag mcp-server-azure-devops-v0.1.45
git push origin mcp-server-azure-devops-v0.1.45

  6. Then use Re-publish the existing release to publish to npm

Verification

After publishing, verify the package is available:

# Check specific version
npm view @tiberriver256/mcp-server-azure-devops@0.1.44

# Check latest version
npm view @tiberriver256/mcp-server-azure-devops version

# Try installing
npm install @tiberriver256/mcp-server-azure-devops@0.1.44

Additional Resources