# Release Troubleshooting Guide
This guide helps you resolve common issues with the release-please automation and npm publishing.
## Table of Contents
- [Understanding the Release Process](#understanding-the-release-process)
- [Common Issues](#common-issues)
- [Failed npm Publish](#failed-npm-publish)
- [Release Already Exists](#release-already-exists)
- [Manual Release Needed](#manual-release-needed)
- [Solutions](#solutions)
- [Re-publishing an Existing Release](#re-publishing-an-existing-release)
- [Force a New Release](#force-a-new-release)
## Understanding the Release Process
The release process uses [release-please](https://github.com/googleapis/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](https://docs.npmjs.com/generating-provenance-statements) 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**:
```bash
# 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](#re-publishing-an-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](#re-publishing-an-existing-release) or [Force a new release](#force-a-new-release)
### Manual Release Needed
**Symptom**: Need to publish a hotfix or re-release immediately.
**Solution**: [Re-publish the existing release](#re-publishing-an-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](../../actions/workflows/release-please.yml) 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`)
- Find tags in the [releases page](../../releases) or [tags page](../../tags)
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:
```bash
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`:
```bash
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:
```bash
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:
```bash
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](#re-publishing-an-existing-release) to publish to npm
## Verification
After publishing, verify the package is available:
```bash
# 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
- [Release Please Documentation](https://github.com/googleapis/release-please)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [npm Publishing Guide](https://docs.npmjs.com/cli/v9/commands/npm-publish)
