docs/AUTOMATED_RELEASES.md
This document describes the automated release system for n8n-mcp, which handles version detection, changelog parsing, and multi-artifact publishing.
The automated release system is triggered when the version in package.json is updated and pushed to the main branch. It handles:
Use the prepared release script for a guided experience:
npm run prepare:release
This script will:
package.json and package.runtime.jsonUpdate the version:
# Edit package.json version field
vim package.json
# Sync to runtime package
npm run sync:runtime-version
Update the changelog:
# Edit docs/CHANGELOG.md
vim docs/CHANGELOG.md
Test and commit:
# 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
The workflow monitors pushes to the main branch and detects when package.json version changes:
paths:
- 'package.json'
- 'package.runtime.json'
Automatically extracts release notes from docs/CHANGELOG.md using the version header format:
## [2.10.0] - 2025-08-02
### Added
- New feature descriptions
### Changed
- Changed feature descriptions
### Fixed
- Bug fix descriptions
vX.Y.Z formatn8n-mcp on npmjs.comnpx usageghcr.io/czlonkowski/n8n-mcp:vX.Y.Zghcr.io/czlonkowski/n8n-mcp-railway:vX.Y.ZvX.Y.Z, vX.Y, vX, latestSet these in GitHub repository settings ā Secrets:
| Secret | Description | Required |
|---|---|---|
DOCKERHUB_USERNAME | Docker Hub username for image pushes | ā Yes |
DOCKERHUB_TOKEN | Docker Hub access token | ā Yes |
GITHUB_TOKEN | Automatically provided by GitHub Actions | ā Auto |
NPM publishing uses npm Trusted Publishers (OIDC) ā no NPM_TOKEN secret is required.
The publish-npm job authenticates to npm via short-lived OIDC tokens minted by GitHub Actions. This is configured once on the npm side:
n8n-mcp.czlonkowskin8n-mcprelease.ymlnpm-publishThe matching GitHub environment must exist (Settings ā Environments ā npm-publish). No protection rules are required, though a required reviewer can be added for an approval gate before each release.
The workflow declares id-token: write and environment: npm-publish on the publish-npm job; npm publish detects the OIDC runtime and authenticates automatically. Provenance attestations are published with every release.
Validate the release system without triggering a release:
npm run test:release-automation
This checks:
Test individual components:
# 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 .
docs/CHANGELOG.md for the current versionpackage.runtime.json for dependenciesMonitor releases at: https://github.com/czlonkowski/n8n-mcp/actions
The workflow provides comprehensive summaries:
Error: 401 Unauthorized
or
npm error code ENEEDAUTH
npm error need auth This command requires you to be logged in
Solution: Verify the Trusted Publisher configuration on npmjs.com matches the workflow:
czlonkowski/n8n-mcprelease.yml (filename only, no path)npm-publishAlso confirm the publish-npm job in the workflow still has permissions: id-token: write and environment: npm-publish. Runner npm must be ā„ 11.5.1 ā the Upgrade npm step handles this.
Error: failed to solve: could not read from registry
Solution: Check GitHub Container Registry permissions and GITHUB_TOKEN.
No changelog entries found for version X.Y.Z
Solution: Ensure changelog follows the correct format:
## [X.Y.Z] - YYYY-MM-DD
Version not incremented
Solution: Ensure new version is greater than the previous version.
npm run prepare:publish
cd npm-publish-temp
npm publish
docker build -t test-build .
git tag -d vX.Y.Z
git push --delete origin vX.Y.Z
The automated system expects changelog entries in Keep a Changelog format:
# 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
...
X.Y.Z-alpha.N - Early developmentX.Y.Z-beta.N - Feature complete, testingX.Y.Z-rc.N - Release candidatePrerelease versions are automatically detected and marked appropriately.
npm run test:release-automationnpm test && npm run buildnpm run prepare:release for guided processnpm run prepare:releaseš¤ This automated release system was designed with Claude Code