Release Process

This document describes the process for creating a new release of n8n-gitops.

Prerequisites

• Write access to the repository
• PyPI trusted publishing configured (see "PyPI Setup" below)
• gh CLI tool installed (optional, for automated release creation)
• All changes merged to main branch
• All tests passing

PyPI Setup (One-Time)

Before your first release, configure PyPI trusted publishing:

1. Create a PyPI account at https://pypi.org/account/register/
2. Go to https://pypi.org/manage/account/publishing/
3. Click "Add a new pending publisher"
4. Fill in the form:
   • PyPI Project Name: n8n-gitops
   • Owner: Your GitHub username/org (e.g., n8n-gitops)
   • Repository name: n8n-gitops
   • Workflow name: build.yml
   • Environment name: (leave blank)
5. Save the pending publisher

The first release will create the PyPI project. Subsequent releases will publish automatically.

Release Checklist

1. Update CHANGELOG

Update CHANGELOG.md with the new version and release notes:

## [X.Y.Z] - YYYY-MM-DD

### Added
- New features

### Changed
- Changes to existing features

### Fixed
- Bug fixes

### Removed
- Removed features

Guidelines:

• Use Keep a Changelog format
• Use ISO date format (YYYY-MM-DD)
• Group changes by category: Added, Changed, Deprecated, Removed, Fixed, Security
• Be descriptive and user-focused
• Include code examples where helpful

2. Commit Changes

git add CHANGELOG.md
git commit -m "Release vX.Y.Z"
git push origin main

3. Create Git Tag

The version is derived automatically from the git tag by setuptools-scm. Create an annotated tag with the version number:

git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

Important: The tag must follow the format vX.Y.Z (with the v prefix) to trigger the GitHub Actions workflow.

4. Wait for CI Build

After pushing the tag:

1. Go to GitHub Actions
2. Wait for the "Build, Lint and Test" workflow to complete
3. Verify all jobs passed:
   • test: Runs tests and linting
   • build: Creates Linux binary
   • publish-pypi: Publishes to PyPI (requires trusted publishing setup)
   • publish-release: Uploads binaries to GitHub release
4. The package will be automatically published to PyPI
5. The Linux binary will be uploaded to the GitHub release

5. Create GitHub Release

Option A: Using GitHub Web Interface

1. Go to Releases
2. Click "Draft a new release"
3. Choose the tag: vX.Y.Z
4. Set the release title: vX.Y.Z or n8n-gitops vX.Y.Z
5. Copy the relevant section from CHANGELOG.md into the release description
6. Download the Linux binary artifact from the GitHub Actions run
7. Attach the binary to the release as n8n-gitops-linux
8. Check "Set as the latest release" (if applicable)
9. Click "Publish release"

Option B: Using GitHub CLI

# Download the artifact from the workflow run
gh run download --name n8n-gitops-linux

# Create the release with the artifact
gh release create vX.Y.Z \
  --title "n8n-gitops vX.Y.Z" \
  --notes-file <(sed -n "/## \[X.Y.Z\]/,/## \[/p" CHANGELOG.md | head -n -1) \
  n8n-gitops-linux/n8n-gitops#n8n-gitops-linux

Release Artifacts

Each release automatically includes:

• Source code (automatically included by GitHub)
• Linux binary: n8n-gitops-linux-amd64.tar.gz and .zip (built by GitHub Actions)
• PyPI package: Published to https://pypi.org/project/n8n-gitops/ (via GitHub Actions)
• Release notes: Extracted from CHANGELOG.md

Post-Release

After creating the release:

1. Verify the release appears on the Releases page
2. Test the binary download and execution
3. Announce the release (if applicable)
4. Close any related milestone

Example: Complete Release Process

Here's a complete example for releasing version 0.3.0:

# 1. Update CHANGELOG.md
# Add section for [0.3.0] with release notes

# 2. Commit changes
git add CHANGELOG.md
git commit -m "Release v0.3.0"
git push origin main

# 3. Create and push tag (this determines the version)
git tag -a v0.3.0 -m "Release v0.3.0"
git push origin v0.3.0

# 4. Wait for GitHub Actions to complete
# Monitor at: https://github.com/YOUR_USERNAME/n8n-gitops/actions

# 5. Create GitHub release
gh run download --name n8n-gitops-linux
gh release create v0.3.0 \
  --title "n8n-gitops v0.3.0" \
  --notes-file <(sed -n "/## \[0.3.0\]/,/## \[/p" CHANGELOG.md | head -n -1) \
  n8n-gitops-linux/n8n-gitops#n8n-gitops-linux

Troubleshooting

Build Fails

If the GitHub Actions build fails:

1. Fix the issue in your code
2. Delete the tag: git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z
3. Start the release process again

Wrong Version Number

If you need to change the version after tagging:

1. Delete the tag: git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z
2. Update the version number
3. Amend the commit: git commit --amend
4. Force push: git push origin main -f
5. Create the tag again

Release Already Exists

If a release with the same tag already exists:

1. Delete the release on GitHub
2. Delete the tag: git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z
3. Start over

Automation Opportunities

Consider automating the release process with:

• GitHub Actions workflow to automatically create releases when tags are pushed
• Release Drafter to automatically generate release notes from PRs
• Semantic Release to automatically determine version numbers based on commit messages

Example automated release workflow (.github/workflows/release.yml):

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4

      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: n8n-gitops-linux
          path: dist/

      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          files: dist/n8n-gitops
          generate_release_notes: true
          draft: false

Notes

• Always test the release binary before publishing
• Keep the CHANGELOG up to date throughout development
• Use semantic versioning consistently
• Coordinate with contributors before major releases
• Consider creating a release candidate (e.g., v1.0.0-rc.1) for major versions