Release Operations Runbook

This runbook covers operational procedures for releasing MCP Hangar.

Table of Contents

• Standard Release
• Emergency Hotfix
• Release Rollback
• Troubleshooting

Standard Release

Prerequisites

• All CI checks passing on main branch
• CHANGELOG.md updated with release notes
• No blocking issues in milestone

Procedure

Step 1: Verify Main Branch State

git checkout main
git pull origin main
git status  # Should be clean

# Run full test suite
uv run pytest tests/ -v
uv run pre-commit run --all-files

Step 2: Initiate Release (Automated via release-please)

Releases are driven by release-please. When Conventional Commit PRs merge to main, release-please opens a release PR that bumps the version and updates the changelog. Merging that PR triggers the release pipeline.

Step 3: Monitor Release Pipeline

After version tag is pushed, the Release workflow triggers automatically:

1. Validate — Checks tag matches pyproject.toml
2. Test — Runs full test matrix (Python 3.11-3.14)
3. Publish PyPI — Builds and uploads to PyPI
4. Publish Docker — Builds multi-arch images, pushes to GHCR
5. Create Release — Creates GitHub Release with changelog

Monitor at: https://github.com/mcp-hangar/mcp-hangar/actions

Step 4: Verify Artifacts

# Verify PyPI package
pip install mcp-hangar==<VERSION> --dry-run

# Verify Docker image
docker pull ghcr.io/mcp-hangar/mcp-hangar:<VERSION>
docker run --rm ghcr.io/mcp-hangar/mcp-hangar:<VERSION> --version

Step 5: Post-Release

• Verify GitHub Release page has correct changelog
• Update documentation site if needed
• Announce in relevant channels (Discord, Slack, etc.)
• Close milestone in GitHub

Emergency Hotfix

Use this procedure for critical bugs in production releases.

Severity Assessment

Procedure

Step 1: Create Hotfix Branch

# From the affected version tag
git fetch --tags
git checkout -b hotfix/X.Y.Z vX.Y.Z-1  # e.g., hotfix/1.0.1 from v1.0.0

Step 2: Apply Fix

# Make minimal fix, add regression test
# ...

# Run tests
uv run pytest tests/ -v

Step 3: Update Version and Changelog

# Update pyproject.toml
sed -i 's/version = ".*"/version = "X.Y.Z"/' pyproject.toml

# Add hotfix entry to CHANGELOG.md
cat >> CHANGELOG_HOTFIX.md << 'EOF'
## [X.Y.Z] - YYYY-MM-DD

### Fixed
- Description of critical fix (#issue)
EOF

# Prepend to CHANGELOG.md after header

Step 4: Tag and Push

git add -A
git commit -m "fix: [CRITICAL] description of fix"
git tag -a vX.Y.Z -m "Hotfix: description"
git push origin hotfix/X.Y.Z
git push origin vX.Y.Z

Step 5: Cherry-pick to Main

git checkout main
git cherry-pick <commit-hash>
git push origin main

Release Rollback

If a release introduces critical issues that can't be hotfixed quickly.

PyPI Rollback

PyPI doesn't allow re-uploading deleted versions. Instead:

1. Yank the version (marks as not recommended):

   Use the PyPI web interface: navigate to https://pypi.org/manage/project/mcp-hangar/release/X.Y.Z/, then click "Yank". There is no CLI command for yanking.

2. Release a new patch version with the fix or revert.

Docker Rollback

1. Update latest tag to previous stable version:

   docker pull ghcr.io/mcp-hangar/mcp-hangar:X.Y.Z-1
   docker tag ghcr.io/mcp-hangar/mcp-hangar:X.Y.Z-1 ghcr.io/mcp-hangar/mcp-hangar:latest
   docker push ghcr.io/mcp-hangar/mcp-hangar:latest

2. Document the issue in GitHub Release notes.

Communication

• Update GitHub Release to mark as "Known Issues"
• Post in announcement channels with:
  • Affected versions
  • Impact description
  • Recommended action (upgrade to X.Y.Z+1 or pin to X.Y.Z-1)

Troubleshooting

Release Workflow Failures

Test Failures

Error: Tests failed on Python 3.X

Resolution:

1. Check test logs in Actions
2. Reproduce locally: uv run pytest tests/ -v --tb=long
3. Fix and push to main
4. Delete failed tag: git push origin :refs/tags/vX.Y.Z
5. Re-run Version Bump workflow

PyPI Publish Failure

Error: 403 Forbidden - trusted publishing not configured

Resolution:

1. Verify PyPI Trusted Publisher is configured:
   • Go to PyPI → Project → Publishing
   • Add GitHub publisher: mcp-hangar/mcp-hangar, workflow release.yml
2. Ensure environment: pypi is set in workflow

Docker Build Failure

Error: buildx failed for linux/arm64

Resolution:

1. Check if Dockerfile has architecture-specific dependencies
2. May need to add platform-specific build stages
3. Consider removing arm64 from platforms temporarily

Version Mismatch

Error: Version mismatch! pyproject.toml: X.Y.Z, Git tag: X.Y.W

Resolution:

1. Either update pyproject.toml to match tag

2. Or delete tag and re-create with correct version:

   git push origin :refs/tags/vX.Y.W
   git tag -d vX.Y.W

Manual Intervention Required

If automated workflows fail and manual release is needed:

# Build package
python -m build

# Upload to PyPI (requires API token)
twine upload dist/*

# Build and push Docker
docker buildx build --platform linux/amd64,linux/arm64 \
  -t ghcr.io/mcp-hangar/mcp-hangar:X.Y.Z \
  -t ghcr.io/mcp-hangar/mcp-hangar:latest \
  --push .

Contacts

Changelog