n8n-mcp/docs/AUTOMATED_RELEASES.md

# 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)*