Skip to content

Publishing PyStator to PyPI

Releases are tag-driven: push a version tag on main and CI runs tests, builds the package (including UI static assets via setup.py), publishes to PyPI, and creates a GitHub Release.

Quick start

  1. From main, create and push a tag (example v0.0.33):
git tag v0.0.33
git push origin v0.0.33

  1. The workflow (.github/workflows/publish.yml) will:

  2. Run the test suite

  3. Build the UI and Python package
  4. Publish to PyPI (Trusted Publishing)
  5. Create a GitHub Release for that tag

The tag is the source of truth for the published version (e.g. v0.0.33 → 0.0.33). Version metadata uses setuptools-scm; you do not need a static version in pyproject.toml for the release to succeed.

Optional: release script

./scripts/release.sh release

The script automates commit/push/merge/tag steps; the workflow still uses the tag for the version published to PyPI.

How it works

Workflow triggers

  • Push to a tag v*: full release (tests → build → PyPI → GitHub Release).
  • Manual workflow_dispatch: may use workflow inputs; see .github/workflows/publish.yml for current behavior.

Trusted Publishing

Configure PyPI Trusted Publishing for this repository and workflow. No long-lived PyPI tokens should be stored in the repo. The workflow needs permissions: id-token: write for OIDC.

Local builds

From the repo root:

make clean && make build    # includes UI refresh when node_modules exists
# or
python -m build

TestPyPI (requires credentials):

export TWINE_PASSWORD=your-testpypi-token
make publish-test

Troubleshooting

  • Workflow did not run: Confirm the tag matches v* and was pushed to the default branch workflow expects.
  • Trusted Publishing failed: Verify the Trusted Publisher entry on PyPI matches this repo and workflow file.
  • Version already on PyPI: Use a new tag (e.g. v0.0.34).

Quick reference

git tag v0.0.33
git push origin v0.0.33