Skip to content

Release Guide

Publishing to PyPI — Trusted Publishing (OIDC)

This project uses PyPI Trusted Publishing instead of a long-lived API token. GitHub Actions receives a short-lived OIDC token automatically; no secrets need to be stored in the repository.

One-time PyPI setup

  1. Log in to pypi.org and open your project (or create it first with an initial manual upload).
  2. Go to Your projects → devpi-gitea-sync → Publishing.
  3. Under Add a new publisher, choose GitHub and fill in:
  4. Owner: veloslab
  5. Repository: python-devpi-gitea-sync
  6. Workflow name: publish.yml
  7. Environment name: leave blank
  8. Click Add.

No PYPI_API_TOKEN secret is needed.

How publishing is triggered

Publishing runs automatically when a GitHub Release is published. The workflow in .github/workflows/publish.yml has two sequential jobs:

ci job: 1. Unit tests (poetry run pytest) 2. Docs build (poetry run mkdocs build --strict)

build-and-publish job (needs: ci — only runs if CI passes): 1. poetry build 2. pypa/gh-action-pypi-publish (uploads dist/ via OIDC)

Release Steps

1. Verify CI is green locally

poetry run pytest
poetry run mkdocs build --strict

2. Create a release branch and bump the version

Change type Command
Bug fixes only poetry version patch — e.g. 0.2.0 → 0.2.1
New features, backwards-compatible poetry version minor — e.g. 0.2.0 → 0.3.0
Breaking changes poetry version major — e.g. 0.2.0 → 1.0.0 
git checkout -b release/v0.2.0
poetry version minor
poetry version   # confirm the new version

3. Commit and open a PR

git add pyproject.toml
git commit -m "Release v0.2.0"
git push origin release/v0.2.0
gh pr create --title "Release v0.2.0" --body "Version bump for v0.2.0."

Wait for CI to pass, then merge.

4. Create a GitHub Release

git checkout main && git pull origin main
gh release create v0.2.0 --title "v0.2.0" --notes "See README for details." --target main

Or via the GitHub UI: Releases → Draft a new release, tag v0.2.0, target main, then Publish release.

5. Verify the release

After the publish workflow completes:

pip install devpi-gitea-sync==0.2.0
devpi-gitea-sync --help

Release Checklist

  • [ ] Tests pass locally (poetry run pytest)
  • [ ] Docs build cleanly (poetry run mkdocs build --strict)
  • [ ] pyproject.toml version bumped via poetry version
  • [ ] Release PR merged and CI green
  • [ ] GitHub Release published (tag vX.Y.Z, target main)
  • [ ] Publish workflow succeeded in GitHub Actions
  • [ ] Package installs cleanly from PyPI