Publishing to PyPI¶
This project publishes the Python package tartan-maker from the public repository
k3jph/tartan-maker. Stable versions
use Git Flow release
branches and a reviewed GitHub Release on the tested main commit.
One-time PyPI account setup¶
The package uses PyPI Trusted Publishing (GitHub Actions OIDC), not a long-lived API token.
- Sign in to the intended project-owner PyPI account at pypi.org.
- For a new
tartan-makerproject, open Account → Publishing and add a pending GitHub trusted publisher. For a project that already exists under your account, use the project's Manage → Publishing page. - Enter the exact values:
| PyPI field | Value |
|---|---|
| PyPI project name (for a pending publisher) | tartan-maker |
| GitHub owner | k3jph |
| GitHub repository | tartan-maker |
| Workflow filename | publish.yml |
| Environment name | pypi |
- In the repository's Settings → Environments, configure an environment
named
pypi. Require approval from a trusted maintainer for deployments, and restrict deployment to release tags matchingv*when supported.
A pending publisher does not reserve the package name until the first successful upload. Do not upload under a different name without updating the project metadata and trusted publisher together.
Before creating a release¶
From a clean checkout of the reviewed release candidate:
python -m pip install -e ".[dev,png]"
python -m pytest -q
ruff check .
python -m pip install build twine
python -m build
python -m twine check --strict dist/*
The GitHub CI workflow also builds the wheel and source distribution, installs
the wheel in a fresh virtual environment, and smoke-tests the tartan-maker
console entry point and a sample SVG export.
Verify that pyproject.toml and src/tartan_maker/_version.py identify the
same version, and that the release notes reflect the final contents.
Publish¶
- Merge the reviewed
release/<version>branch tomainonly after CI passes. - On GitHub, create a new GitHub Release based on the verified
maincommit, with tagv<version>(for example,v1.0.0). - Publishing the GitHub Release starts
.github/workflows/publish.yml. The workflow checks the release tag against the package version, builds the sdist and wheel, validates metadata, and requests approval through thepypienvironment. - After the approved publish job succeeds, verify the live project at PyPI and test in a fresh environment:
Never put PyPI passwords, API tokens, or session cookies in GitHub or repository files. If the workflow fails with a trusted-publisher identity error, check the exact owner/repository/workflow/environment fields on PyPI before retrying. A version already accepted by PyPI cannot be overwritten; fix the source and publish a new patch version instead.
For the authoritative procedure, see PyPI's Trusted Publisher guide.