ci: Switch to tag-based publishing workflow

facundofarias · claude · facundofarias · commit 96f1831bdb47 · 2025-11-11T10:01:24.000+01:00
Change from automatic publishing on main merge to tag-based releases for better control over when packages are published. Changes: - Update publish.yml to trigger on version tags (v*) - Add version validation (tag must match package.json) - Update workflow documentation with tag-based process - Add comprehensive RELEASING.md guide for maintainers Benefits: - Control when releases happen (not every merge) - Can batch multiple PRs into one release - Clear release process with version bumping - Standard practice in open source projects Publishing process: 1. npm version patch/minor/major 2. git push origin main --tags 3. GitHub Actions publishes automatically See RELEASING.md for complete release checklist. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/.github/workflows/README.md b/.github/workflows/README.md
@@ -21,18 +21,18 @@ This repository uses GitHub Actions for continuous integration and automated npm
 
 ### 2. Publish Workflow (`publish.yml`)
 
-**Triggers**: Automatically after CI workflow succeeds on `main` branch
+**Triggers**: When a version tag is pushed (e.g., `v1.0.0`)
 
 **What it does**:
-1. Waits for CI workflow to complete successfully
-2. Checks out code and installs dependencies
-3. Builds the project
-4. Extracts version from `package.json`
+1. Checks out code and installs dependencies
+2. Builds the project
+3. Extracts version from `package.json`
+4. Verifies tag version matches package.json version
 5. Verifies package contents with `npm pack --dry-run`
 6. Publishes to npm registry (public package)
-7. Creates GitHub Release with tag `v{version}`
+7. Creates GitHub Release with version notes
 
-**Dependencies**: Only runs if CI workflow passes
+**Note**: CI workflow should pass before creating release tags
 
 ## Setup Requirements
 
@@ -58,32 +58,45 @@ The `GITHUB_TOKEN` is automatically provided by GitHub Actions - no setup needed
 
 ## Publishing Process
 
-### Automatic Publishing (Recommended)
+### Tag-Based Publishing (Recommended)
 
-When you merge to `main`:
+Releases are triggered by pushing version tags:
 
 ```bash
-# 1. Create PR with version bump
-git checkout -b release/v1.0.1
-npm version patch  # or minor, major
-git push origin release/v1.0.1
+# 1. Ensure you're on main with latest changes
+git checkout main
+git pull origin main
+
+# 2. Ensure CI is passing
+# Check: https://github.com/deployhq/deployhq-mcp-server/actions
+
+# 3. Bump version in package.json
+npm version patch  # 1.0.0 -> 1.0.1 (bug fixes)
+npm version minor  # 1.0.0 -> 1.1.0 (new features)
+npm version major  # 1.0.0 -> 2.0.0 (breaking changes)
+
+# 4. Push commit and tag
+git push origin main
+git push origin --tags
 
-# 2. Create and merge PR to main
 # GitHub Actions will automatically:
-# - Run CI tests
-# - Publish to npm (if CI passes)
+# - Build the project
+# - Verify tag matches package.json version
+# - Publish to npm
 # - Create GitHub release
 ```
 
 ### Manual Publishing (Not Recommended)
 
-If you need to publish manually:
+If automated publishing fails, you can publish manually:
 
 ```bash
 npm run build
 npm publish
 ```
 
+**Important**: Only use manual publishing as a last resort. The automated workflow is more reliable and creates proper GitHub releases.
+
 ## Version Management
 
 Follow semantic versioning (SemVer):
@@ -118,15 +131,23 @@ Follow semantic versioning (SemVer):
 │  ├─ Test (108 tests)                                │
 │  ├─ Build                                           │
 │  └─ Verify artifacts                                │
+└─────────────────────────────────────────────────────┘
+
+                 (manually create release)
+
+┌─────────────────────────────────────────────────────┐
+│  Developer creates version tag                      │
+│  $ npm version patch                                │
+│  $ git push origin main --tags                      │
 └────────────────┬────────────────────────────────────┘
                  │
-                 │ (only on main branch)
                  ▼
 ┌─────────────────────────────────────────────────────┐
 │  Publish Workflow (publish.yml)                     │
-│  ├─ Wait for CI to succeed                          │
+│  ├─ Triggered by version tag (v*)                   │
 │  ├─ Build project                                   │
-│  ├─ Verify package                                  │
+│  ├─ Verify tag matches package.json                 │
+│  ├─ Verify package contents                         │
 │  ├─ Publish to npm                                  │
 │  └─ Create GitHub Release                           │
 └─────────────────────────────────────────────────────┘
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -1,19 +1,15 @@
 name: Publish to npm
 
 on:
-  workflow_run:
-    workflows: ["CI"]
-    types: [completed]
-    branches: [main]
+  push:
+    tags:
+      - 'v*'  # Trigger on version tags like v1.0.0, v1.2.3, etc.
 
 jobs:
   publish:
     name: Publish to npm
     runs-on: ubuntu-latest
 
-    # Only run if CI workflow succeeded
-    if: ${{ github.event.workflow_run.conclusion == 'success' }}
-
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -35,6 +31,16 @@ jobs:
         id: package-version
         run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
 
+      - name: Verify tag matches package version
+        run: |
+          TAG_VERSION=${GITHUB_REF#refs/tags/v}
+          PACKAGE_VERSION=${{ steps.package-version.outputs.version }}
+          if [ "$TAG_VERSION" != "$PACKAGE_VERSION" ]; then
+            echo "Error: Git tag version ($TAG_VERSION) does not match package.json version ($PACKAGE_VERSION)"
+            exit 1
+          fi
+          echo "✓ Tag version matches package.json version: $TAG_VERSION"
+
       - name: Verify package contents
         run: |
           echo "Verifying package contents for v${{ steps.package-version.outputs.version }}..."
diff --git a/README.md b/README.md
@@ -574,6 +574,10 @@ Contributions are welcome! Please:
 4. Add tests if applicable
 5. Submit a pull request
 
+### For Maintainers
+
+See [RELEASING.md](RELEASING.md) for instructions on creating releases and publishing to npm.
+
 ## 📄 License
 
 MIT License - see LICENSE file for details
@@ -582,7 +586,7 @@ MIT License - see LICENSE file for details
 
 - **DeployHQ API Documentation**: https://www.deployhq.com/support/api
 - **MCP Documentation**: https://modelcontextprotocol.io
-- **Issues**: https://github.com/your-username/deployhq-mcp-server/issues
+- **Issues**: https://github.com/deployhq/deployhq-mcp-server/issues
 
 ## 🔗 Related Links
 
diff --git a/RELEASING.md b/RELEASING.md
@@ -0,0 +1,227 @@
+# Release Process
+
+This document describes how to create a new release of the DeployHQ MCP Server.
+
+## Prerequisites
+
+Before creating a release, ensure you have:
+
+- [ ] Maintainer access to the GitHub repository
+- [ ] npm publish access (verify with `npm whoami`)
+- [ ] Local `main` branch is up to date
+- [ ] All CI checks are passing on `main`
+
+## Release Types
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **Patch** (`1.0.x`): Bug fixes, documentation updates, minor improvements
+- **Minor** (`1.x.0`): New features, non-breaking changes
+- **Major** (`x.0.0`): Breaking changes, major rewrites
+
+## Release Checklist
+
+### 1. Prepare the Release
+
+```bash
+# Ensure you're on main with latest changes
+git checkout main
+git pull origin main
+
+# Verify CI is passing
+# Check: https://github.com/deployhq/deployhq-mcp-server/actions
+
+# Run tests locally
+npm test
+
+# Build locally to verify
+npm run build
+```
+
+### 2. Update Version and Changelog
+
+```bash
+# Choose the appropriate version bump
+npm version patch  # For bug fixes (1.0.0 -> 1.0.1)
+npm version minor  # For new features (1.0.0 -> 1.1.0)
+npm version major  # For breaking changes (1.0.0 -> 2.0.0)
+
+# This will:
+# - Update package.json version
+# - Create a git commit "1.0.1"
+# - Create a git tag "v1.0.1"
+```
+
+**Optional**: Update CHANGELOG.md with release notes before running `npm version`.
+
+### 3. Push Changes and Tags
+
+```bash
+# Push the version commit
+git push origin main
+
+# Push the version tag (triggers publish workflow)
+git push origin --tags
+```
+
+### 4. Monitor the Release
+
+1. **Watch GitHub Actions**: https://github.com/deployhq/deployhq-mcp-server/actions
+   - Wait for "Publish to npm" workflow to complete
+   - Should take ~2-3 minutes
+
+2. **Verify npm Publication**: https://www.npmjs.com/package/deployhq-mcp-server
+   - Check that new version appears
+   - Verify package contents are correct
+
+3. **Check GitHub Release**: https://github.com/deployhq/deployhq-mcp-server/releases
+   - Verify release was created automatically
+   - Edit release notes if needed
+
+### 5. Verify the Release
+
+```bash
+# Test installing from npm
+npx deployhq-mcp-server@latest --version
+
+# Or install in a test project
+mkdir test-install && cd test-install
+npm init -y
+npm install deployhq-mcp-server
+node -e "import('deployhq-mcp-server')"
+```
+
+### 6. Announce the Release (Optional)
+
+If it's a significant release:
+- Update README.md if needed
+- Post announcement (Discord, Twitter, etc.)
+- Update documentation site
+
+## Troubleshooting
+
+### Publish Workflow Failed
+
+**Check the logs**:
+```bash
+# View workflow runs
+https://github.com/deployhq/deployhq-mcp-server/actions
+```
+
+**Common issues**:
+
+1. **Tag version mismatch**
+   - Error: "Git tag version does not match package.json version"
+   - Fix: Ensure tag and package.json versions match
+   ```bash
+   # Delete the tag locally and remotely
+   git tag -d v1.0.1
+   git push origin :refs/tags/v1.0.1
+
+   # Fix package.json version and create tag again
+   npm version 1.0.1
+   git push origin main --tags
+   ```
+
+2. **npm publish failed - version already exists**
+   - Error: "Cannot publish over existing version"
+   - Fix: Version was already published, bump to next version
+   ```bash
+   npm version patch
+   git push origin main --tags
+   ```
+
+3. **npm publish failed - authentication**
+   - Error: "authentication failed"
+   - Fix: Check NPM_TOKEN secret in GitHub
+   - Go to: Settings → Secrets → Actions → NPM_TOKEN
+   - Regenerate token: `npm token create --type automation`
+
+4. **Build failed**
+   - Run build locally to diagnose: `npm run build`
+   - Fix issues and commit to main
+   - Delete failed tag and recreate
+
+### Manual Rollback
+
+If a published version has critical issues:
+
+```bash
+# Deprecate the broken version on npm
+npm deprecate deployhq-mcp-server@1.0.1 "Critical bug, use 1.0.2 instead"
+
+# Create a hotfix release
+npm version patch
+git push origin main --tags
+```
+
+**Note**: You cannot unpublish versions after 72 hours. Use deprecation instead.
+
+### Manual Publishing (Emergency Only)
+
+If the automated workflow is broken:
+
+```bash
+# Ensure you're logged in
+npm whoami
+
+# Build the project
+npm run build
+
+# Publish manually
+npm publish
+
+# Manually create GitHub release
+# Go to: https://github.com/deployhq/deployhq-mcp-server/releases/new
+```
+
+## Version History
+
+Track versions and release dates:
+
+| Version | Date | Type | Notes |
+|---------|------|------|-------|
+| 1.0.0 | 2025-11-11 | Initial | First stable release |
+
+## Best Practices
+
+### DO:
+- ✅ Always run tests before releasing
+- ✅ Ensure CI passes before tagging
+- ✅ Test the package after publishing
+- ✅ Use semantic versioning correctly
+- ✅ Write clear release notes
+- ✅ Batch multiple small changes into one release
+
+### DON'T:
+- ❌ Force push to main
+- ❌ Delete published npm versions (use deprecate)
+- ❌ Skip version bumps in package.json
+- ❌ Publish breaking changes as patches
+- ❌ Release on Friday afternoon (Murphy's Law)
+
+## Release Cadence
+
+**Suggested schedule**:
+- **Patch releases**: As needed for bugs (any time)
+- **Minor releases**: Weekly or bi-weekly for features
+- **Major releases**: Quarterly or when necessary for breaking changes
+
+## Questions?
+
+- Check `.github/workflows/README.md` for CI/CD details
+- Check `package.json` for current version
+- Check GitHub Actions for workflow status
+- Check npm for published versions
+
+## Quick Reference
+
+```bash
+# Complete release in 4 commands
+git checkout main && git pull
+npm version patch
+git push origin main
+git push origin --tags
+```
+
+Then monitor: https://github.com/deployhq/deployhq-mcp-server/actions
