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:

Prompt for the new version
Update package.json and package.runtime.json
Update the changelog
Run tests and build
Create a git commit
Optionally push to trigger the release

Manual Process

Update the version:

bash

# Edit package.json version field
vim package.json

# Sync to runtime package
npm run sync:runtime-version

Update the changelog:

bash

# Edit docs/CHANGELOG.md
vim docs/CHANGELOG.md

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

Login to npmjs.com
Go to Account Settings → Access Tokens
Create a new Automation token
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

Check if version was already published

If not, manually publish:

bash

npm run prepare:publish
cd npm-publish-temp
npm publish

Failed Docker Build

Build locally to test:
bash
```
docker build -t test-build .
```
Re-trigger workflow or push a fix

Incomplete Release

Delete the created tag if needed:

bash

git tag -d vX.Y.Z
git push --delete origin vX.Y.Z

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 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

✅ Run npm run test:release-automation
✅ Update changelog with meaningful descriptions
✅ Test locally with npm test && npm run build
✅ Review breaking changes
✅ 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

Use automated tools: npm run prepare:release
Follow semantic versioning
Update changelog thoroughly
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