feat: add automated release workflow for npm publishing
- Add release.yml GitHub workflow for automated npm releases - Add prepare-release.js script for version bumping and changelog - Add extract-changelog.js for release notes extraction - Add test-release-automation.js for testing the workflow - Add documentation for automated releases This enables automatic npm publishing when tags are pushed, fixing the issue where releases were created but npm packages were not published. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
384
docs/AUTOMATED_RELEASES.md
Normal file
384
docs/AUTOMATED_RELEASES.md
Normal file
@@ -0,0 +1,384 @@
|
||||
# Automated Release Process
|
||||
|
||||
This document describes the automated release system for n8n-mcp, which handles version detection, changelog parsing, and multi-artifact publishing.
|
||||
|
||||
## Overview
|
||||
|
||||
The automated release system is triggered when the version in `package.json` is updated and pushed to the main branch. It handles:
|
||||
|
||||
- 🏷️ **GitHub Releases**: Creates releases with changelog content
|
||||
- 📦 **NPM Publishing**: Publishes optimized runtime package
|
||||
- 🐳 **Docker Images**: Builds and pushes multi-platform images
|
||||
- 📚 **Documentation**: Updates version badges automatically
|
||||
|
||||
## Quick Start
|
||||
|
||||
### For Maintainers
|
||||
|
||||
Use the prepared release script for a guided experience:
|
||||
|
||||
```bash
|
||||
npm run prepare:release
|
||||
```
|
||||
|
||||
This script will:
|
||||
1. Prompt for the new version
|
||||
2. Update `package.json` and `package.runtime.json`
|
||||
3. Update the changelog
|
||||
4. Run tests and build
|
||||
5. Create a git commit
|
||||
6. Optionally push to trigger the release
|
||||
|
||||
### Manual Process
|
||||
|
||||
1. **Update the version**:
|
||||
```bash
|
||||
# Edit package.json version field
|
||||
vim package.json
|
||||
|
||||
# Sync to runtime package
|
||||
npm run sync:runtime-version
|
||||
```
|
||||
|
||||
2. **Update the changelog**:
|
||||
```bash
|
||||
# Edit docs/CHANGELOG.md
|
||||
vim docs/CHANGELOG.md
|
||||
```
|
||||
|
||||
3. **Test and commit**:
|
||||
```bash
|
||||
# Ensure everything works
|
||||
npm test
|
||||
npm run build
|
||||
npm run rebuild
|
||||
|
||||
# Commit changes
|
||||
git add package.json package.runtime.json docs/CHANGELOG.md
|
||||
git commit -m "chore: release vX.Y.Z"
|
||||
git push
|
||||
```
|
||||
|
||||
## Workflow Details
|
||||
|
||||
### Version Detection
|
||||
|
||||
The workflow monitors pushes to the main branch and detects when `package.json` version changes:
|
||||
|
||||
```yaml
|
||||
paths:
|
||||
- 'package.json'
|
||||
- 'package.runtime.json'
|
||||
```
|
||||
|
||||
### Changelog Parsing
|
||||
|
||||
Automatically extracts release notes from `docs/CHANGELOG.md` using the version header format:
|
||||
|
||||
```markdown
|
||||
## [2.10.0] - 2025-08-02
|
||||
|
||||
### Added
|
||||
- New feature descriptions
|
||||
|
||||
### Changed
|
||||
- Changed feature descriptions
|
||||
|
||||
### Fixed
|
||||
- Bug fix descriptions
|
||||
```
|
||||
|
||||
### Release Artifacts
|
||||
|
||||
#### GitHub Release
|
||||
- Created with extracted changelog content
|
||||
- Tagged with `vX.Y.Z` format
|
||||
- Includes installation instructions
|
||||
- Links to documentation
|
||||
|
||||
#### NPM Package
|
||||
- Published as `n8n-mcp` on npmjs.com
|
||||
- Uses runtime-only dependencies (8 packages vs 50+ dev deps)
|
||||
- Optimized for `npx` usage
|
||||
- ~50MB vs 1GB+ with dev dependencies
|
||||
|
||||
#### Docker Images
|
||||
- **Standard**: `ghcr.io/czlonkowski/n8n-mcp:vX.Y.Z`
|
||||
- **Railway**: `ghcr.io/czlonkowski/n8n-mcp-railway:vX.Y.Z`
|
||||
- Multi-platform: linux/amd64, linux/arm64
|
||||
- Semantic version tags: `vX.Y.Z`, `vX.Y`, `vX`, `latest`
|
||||
|
||||
## Configuration
|
||||
|
||||
### Required Secrets
|
||||
|
||||
Set these in GitHub repository settings → Secrets:
|
||||
|
||||
| Secret | Description | Required |
|
||||
|--------|-------------|----------|
|
||||
| `NPM_TOKEN` | NPM authentication token for publishing | ✅ Yes |
|
||||
| `GITHUB_TOKEN` | Automatically provided by GitHub Actions | ✅ Auto |
|
||||
|
||||
### NPM Token Setup
|
||||
|
||||
1. Login to [npmjs.com](https://www.npmjs.com)
|
||||
2. Go to Account Settings → Access Tokens
|
||||
3. Create a new **Automation** token
|
||||
4. Add as `NPM_TOKEN` secret in GitHub
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Release Automation
|
||||
|
||||
Validate the release system without triggering a release:
|
||||
|
||||
```bash
|
||||
npm run test:release-automation
|
||||
```
|
||||
|
||||
This checks:
|
||||
- ✅ File existence and structure
|
||||
- ✅ Version detection logic
|
||||
- ✅ Changelog parsing
|
||||
- ✅ Build process
|
||||
- ✅ NPM package preparation
|
||||
- ✅ Docker configuration
|
||||
- ✅ Workflow syntax
|
||||
- ✅ Environment setup
|
||||
|
||||
### Local Testing
|
||||
|
||||
Test individual components:
|
||||
|
||||
```bash
|
||||
# Test version detection
|
||||
node -e "console.log(require('./package.json').version)"
|
||||
|
||||
# Test changelog parsing
|
||||
node scripts/test-release-automation.js
|
||||
|
||||
# Test npm package preparation
|
||||
npm run prepare:publish
|
||||
|
||||
# Test Docker build
|
||||
docker build -t test-image .
|
||||
```
|
||||
|
||||
## Workflow Jobs
|
||||
|
||||
### 1. Version Detection
|
||||
- Compares current vs previous version in git history
|
||||
- Determines if it's a prerelease (alpha, beta, rc, dev)
|
||||
- Outputs version information for other jobs
|
||||
|
||||
### 2. Changelog Extraction
|
||||
- Parses `docs/CHANGELOG.md` for the current version
|
||||
- Extracts content between version headers
|
||||
- Provides formatted release notes
|
||||
|
||||
### 3. GitHub Release Creation
|
||||
- Creates annotated git tag
|
||||
- Creates GitHub release with changelog content
|
||||
- Handles prerelease flag for alpha/beta versions
|
||||
|
||||
### 4. Build and Test
|
||||
- Installs dependencies
|
||||
- Runs full test suite
|
||||
- Builds TypeScript
|
||||
- Rebuilds node database
|
||||
- Type checking
|
||||
|
||||
### 5. NPM Publishing
|
||||
- Prepares optimized package structure
|
||||
- Uses `package.runtime.json` for dependencies
|
||||
- Publishes to npmjs.com registry
|
||||
- Automatic cleanup
|
||||
|
||||
### 6. Docker Building
|
||||
- Multi-platform builds (amd64, arm64)
|
||||
- Two image variants (standard, railway)
|
||||
- Semantic versioning tags
|
||||
- GitHub Container Registry
|
||||
|
||||
### 7. Documentation Updates
|
||||
- Updates version badges in README
|
||||
- Commits documentation changes
|
||||
- Automatic push back to repository
|
||||
|
||||
## Monitoring
|
||||
|
||||
### GitHub Actions
|
||||
Monitor releases at: https://github.com/czlonkowski/n8n-mcp/actions
|
||||
|
||||
### Release Status
|
||||
- **GitHub Releases**: https://github.com/czlonkowski/n8n-mcp/releases
|
||||
- **NPM Package**: https://www.npmjs.com/package/n8n-mcp
|
||||
- **Docker Images**: https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp
|
||||
|
||||
### Notifications
|
||||
|
||||
The workflow provides comprehensive summaries:
|
||||
- ✅ Success notifications with links
|
||||
- ❌ Failure notifications with error details
|
||||
- 📊 Artifact information and installation commands
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### NPM Publishing Fails
|
||||
```
|
||||
Error: 401 Unauthorized
|
||||
```
|
||||
**Solution**: Check NPM_TOKEN secret is valid and has publishing permissions.
|
||||
|
||||
#### Docker Build Fails
|
||||
```
|
||||
Error: failed to solve: could not read from registry
|
||||
```
|
||||
**Solution**: Check GitHub Container Registry permissions and GITHUB_TOKEN.
|
||||
|
||||
#### Changelog Parsing Fails
|
||||
```
|
||||
No changelog entries found for version X.Y.Z
|
||||
```
|
||||
**Solution**: Ensure changelog follows the correct format:
|
||||
```markdown
|
||||
## [X.Y.Z] - YYYY-MM-DD
|
||||
```
|
||||
|
||||
#### Version Detection Fails
|
||||
```
|
||||
Version not incremented
|
||||
```
|
||||
**Solution**: Ensure new version is greater than the previous version.
|
||||
|
||||
### Recovery Steps
|
||||
|
||||
#### Failed NPM Publish
|
||||
1. Check if version was already published
|
||||
2. If not, manually publish:
|
||||
```bash
|
||||
npm run prepare:publish
|
||||
cd npm-publish-temp
|
||||
npm publish
|
||||
```
|
||||
|
||||
#### Failed Docker Build
|
||||
1. Build locally to test:
|
||||
```bash
|
||||
docker build -t test-build .
|
||||
```
|
||||
2. Re-trigger workflow or push a fix
|
||||
|
||||
#### Incomplete Release
|
||||
1. Delete the created tag if needed:
|
||||
```bash
|
||||
git tag -d vX.Y.Z
|
||||
git push --delete origin vX.Y.Z
|
||||
```
|
||||
2. Fix issues and push again
|
||||
|
||||
## Security
|
||||
|
||||
### Secrets Management
|
||||
- NPM_TOKEN has limited scope (publish only)
|
||||
- GITHUB_TOKEN has automatic scoping
|
||||
- No secrets are logged or exposed
|
||||
|
||||
### Package Security
|
||||
- Runtime package excludes development dependencies
|
||||
- No build tools or test frameworks in published package
|
||||
- Minimal attack surface (~50MB vs 1GB+)
|
||||
|
||||
### Docker Security
|
||||
- Multi-stage builds
|
||||
- Non-root user execution
|
||||
- Minimal base images
|
||||
- Security scanning enabled
|
||||
|
||||
## Changelog Format
|
||||
|
||||
The automated system expects changelog entries in [Keep a Changelog](https://keepachangelog.com/) format:
|
||||
|
||||
```markdown
|
||||
# Changelog
|
||||
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
- New features for next release
|
||||
|
||||
## [2.10.0] - 2025-08-02
|
||||
|
||||
### Added
|
||||
- Automated release system
|
||||
- Multi-platform Docker builds
|
||||
|
||||
### Changed
|
||||
- Improved version detection
|
||||
- Enhanced error handling
|
||||
|
||||
### Fixed
|
||||
- Fixed changelog parsing edge cases
|
||||
- Fixed Docker build optimization
|
||||
|
||||
## [2.9.1] - 2025-08-01
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
## Version Strategy
|
||||
|
||||
### Semantic Versioning
|
||||
- **MAJOR** (X.0.0): Breaking changes
|
||||
- **MINOR** (X.Y.0): New features, backward compatible
|
||||
- **PATCH** (X.Y.Z): Bug fixes, backward compatible
|
||||
|
||||
### Prerelease Versions
|
||||
- **Alpha**: `X.Y.Z-alpha.N` - Early development
|
||||
- **Beta**: `X.Y.Z-beta.N` - Feature complete, testing
|
||||
- **RC**: `X.Y.Z-rc.N` - Release candidate
|
||||
|
||||
Prerelease versions are automatically detected and marked appropriately.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Before Releasing
|
||||
1. ✅ Run `npm run test:release-automation`
|
||||
2. ✅ Update changelog with meaningful descriptions
|
||||
3. ✅ Test locally with `npm test && npm run build`
|
||||
4. ✅ Review breaking changes
|
||||
5. ✅ Consider impact on users
|
||||
|
||||
### Version Bumping
|
||||
- Use `npm run prepare:release` for guided process
|
||||
- Follow semantic versioning strictly
|
||||
- Document breaking changes clearly
|
||||
- Consider backward compatibility
|
||||
|
||||
### Changelog Writing
|
||||
- Be specific about changes
|
||||
- Include migration notes for breaking changes
|
||||
- Credit contributors
|
||||
- Use consistent formatting
|
||||
|
||||
## Contributing
|
||||
|
||||
### For Maintainers
|
||||
1. Use automated tools: `npm run prepare:release`
|
||||
2. Follow semantic versioning
|
||||
3. Update changelog thoroughly
|
||||
4. Test before releasing
|
||||
|
||||
### For Contributors
|
||||
- Breaking changes require MAJOR version bump
|
||||
- New features require MINOR version bump
|
||||
- Bug fixes require PATCH version bump
|
||||
- Update changelog in PR descriptions
|
||||
|
||||
---
|
||||
|
||||
🤖 *This automated release system was designed with [Claude Code](https://claude.ai/code)*
|
||||
Reference in New Issue
Block a user