Skip to main content
Syft-Flwr uses a fully automated release process via GitHub Actions. This guide covers how to release new versions, test releases, and troubleshoot common issues.

​
Quick Release

Releasing a new version is simple and fully automated:
1

Navigate to Actions

Go to the GitHub repository → Actions tab
2

Select Release workflow

Click on Release workflow from the list
3

Run workflow

Click “Run workflow” button
4

Configure release

Select the following options:
  • bump_type: Choose patch, minor, or major
  • skip_publish: Leave unchecked (false) for production release
5

Execute

Click “Run workflow” to start the release process
The workflow will automatically handle everything from version bumping to PyPI publishing.

​
What the Workflow Does

The release workflow performs the following steps automatically:
1

Setup Environment

  • Checks out the main branch
  • Installs Python, uv, just, and all dependencies
2

Version Bump

Uses just bump <type> which:
  • Runs cz bump (commitizen) to update version numbers
  • Creates a git commit and tag
  • Updates main project’s uv.lock file
  • Updates notebook pyproject.toml files (locks updated later)
  • Amends everything into a single atomic commit
3

Testing & Building

  • Runs full test suite (just test)
  • Builds the package (just build)
  • Tests the built package can be imported
  • Verifies the version number is correct
4

Publishing

  • Pushes the commit and tags to main branch
  • Uploads the package to PyPI (unless skip_publish=true)
  • Creates a GitHub release with auto-generated changelog
5

Post-publish Updates

  • Waits 30 seconds for PyPI to index the new version
  • Updates notebook lock files with the published version
  • Commits and pushes the lock file updates

​
Testing a Release

Before releasing to production, you can test the release process without making permanent changes:
1

Run workflow in test mode

When running the Release workflow, set skip_publish to true (check the box)
2

What gets tested

The workflow will:
  • ✅ Test version bumping and dependency updates
  • ✅ Build and validate the package
  • ❌ Skip git commits/pushes (no permanent changes)
  • ❌ Skip PyPI upload
  • ❌ Skip GitHub release creation
  • ❌ Skip notebook lock file updates
3

Review logs

Review the workflow logs to ensure everything works correctly
4

No cleanup needed

No permanent changes are made, so no cleanup is required

​
Manual Release Steps

If you need to release manually (for example, if the GitHub Actions workflow is unavailable):
1

Bump version

just bump patch  # or minor/major
This updates version numbers, creates a commit and tag.
2

Run tests

just test
Ensure all tests pass before releasing.
3

Build package

just build
Creates distribution files in the dist/ directory.
4

Push to GitHub

git push origin main --tags
Pushes the version commit and tag to the main branch.
5

Upload to PyPI

uvx twine upload dist/* --username __token__ --password <token>
Replace <token> with your PyPI API token.
6

Update notebook locks

After PyPI publishes the package (wait a few minutes):
just update-notebook-locks
git add notebooks/*/uv.lock
git commit -m "chore: update notebook locks"
git push origin main

​
Version Bumping

The project uses Commitizen for version management.

​
Available Commands

just bump patch

​
What Gets Updated

Commitizen automatically updates version numbers in multiple files:
  1. pyproject.toml: Main project version
  2. src/syft_flwr/__init__.py: Package __version__ variable
  3. notebooks/*/pyproject.toml: Notebook dependency versions
This is configured in pyproject.toml:
pyproject.toml
[tool.commitizen]
name = "cz_conventional_commits"
version_provider = "pep621"
tag_format = "v$version"
update_changelog_on_bump = false
version_files = [
    "pyproject.toml:^version\\s*=\\s*\"(?P<version>.*)\"$",
    "src/syft_flwr/__init__.py:^__version__\\s*=\\s*\"(?P<version>.*)\"$",
    "notebooks/*/pyproject.toml:\"syft-flwr>=(?P<version>[^\"]+)\"",
]

​
Troubleshooting

Problem: Notebook lock file updates fail after publishing.Solution: The new version might not be available on PyPI yet. Wait a few minutes and run manually:
just update-notebook-locks
git add notebooks/*/uv.lock
git commit -m "chore: update notebook locks"
git push origin main
Problem: Release workflow fails because tests don’t pass.Solution:
  • Fix the failing tests before attempting release
  • The workflow will abort if tests fail
  • Never bypass failing tests in production releases
Problem: Package upload to PyPI fails.Possible causes:
  • OM_PYPI_TOKEN secret is not set or invalid in repository settings
  • The version already exists on PyPI (versions are immutable)
  • Network or PyPI service issues
Solution:
Problem: Version number already exists or conflicts.Solution:
  • PyPI versions are immutable and cannot be reused
  • Bump to a higher version number
  • Use just show-version to check current version
  • Use just bump-dry patch to preview next version
Problem: Git tag for version already exists.Solution:
# Delete local tag
git tag -d v0.5.0

# Delete remote tag (use with caution)
git push origin :refs/tags/v0.5.0

# Bump to next version
just bump patch

​
Development Workflow

The recommended workflow for development and releases:
1

Feature Development

Develop features in feature branches:
git checkout -b feature/new-feature
# Make changes, commit, test
2

Merge to Main

Create a pull request and merge to main when ready:
git checkout main
git pull origin main
git merge feature/new-feature
git push origin main
3

Run Release Workflow

Trigger the release workflow from GitHub Actions to publish the new version
4

Notebook Updates

Notebook dependencies are automatically updated by the release workflow
This ensures the main branch is always releasable and dependencies stay in sync.

​
Required Secrets

The following GitHub repository secrets must be configured for automated releases:
Secret NameDescription
OM_PYPI_TOKENPyPI API token for uploading packages

​
Setting Up PyPI Token

1

Create PyPI token

  1. Log in to PyPI
  2. Go to Account Settings → API tokens
  3. Click “Add API token”
  4. Set scope to “Entire account” or specific to “syft-flwr” project
  5. Copy the token (starts with pypi-)
2

Add to GitHub secrets

  1. Go to repository → Settings → Secrets and variables → Actions
  2. Click “New repository secret”
  3. Name: OM_PYPI_TOKEN
  4. Value: Paste the PyPI token
  5. Click “Add secret”

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us