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.

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

1. 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:
2. Go to PyPI → Project → Publishing
3. Add GitHub publisher: mcp-hangar/mcp-hangar, workflow release.yml
4. 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¶