The publish workflow coordinates multiple guarded steps to move a package version from source control to public repositories. The flow below mirrors the PUBLISH_STEPS sequence used by the release UI and the headless scheduler.
flowchart TD
A[Start release from admin or scheduler] --> B[Check version number availability]
B -->|Clean repo & ensure version not on PyPI| C[Freeze, squash and approve migrations]
C --> D[Execute pre-release actions]
D -->|Sync main, bump VERSION, stage fixtures| E[Build release artifacts]
E -->|Promote build, commit metadata, push| F[Complete test suite with --all flag]
F --> TP[Confirm PyPI Trusted Publisher settings]
TP --> G[Verify release environment]
G -->|Environment ready| H[Export artifacts and push release tag]
H --> I[Wait for GitHub Actions publish]
I --> J[Record publish URLs & update fixtures after publish]
J --> K[Capture PyPI publish logs]
K --> L[Finish and log completion]
B -->|Dirty repo or version conflict| B
Step-by-step breakdown
Check version number availability – Syncs with origin/main, enforces a clean working tree (auto-committing allowed fixture/VERSION changes when possible), and confirms the requested version is newer than the repository state and not already present on PyPI. The step halts on dirty repositories or conflicting versions to avoid accidental overwrites.
Freeze, squash and approve migrations – Serves as a manual checkpoint to review migration changes. The workflow logs the acknowledgement and expects developers to ensure migrations are consolidated appropriately before proceeding.
Execute pre-release actions – Refreshes release fixtures, updates the VERSION file to the target value, stages the changes, and commits them if anything changed. The workflow also tracks the pre-sync version to support clean restarts.
Build release artifacts – Re-validates that origin/main is unchanged, promotes the build via release_utils.promote, and commits any updated metadata (e.g., VERSION, release fixtures). The step sets the build revision and renames the log to the release-specific filename, ensuring traceability.
Complete test suite with --all flag – Captures the expectation that the full test suite has been executed with the --all flag. The UI records acknowledgement, keeping the workflow consistent even when tests run externally.
Confirm PyPI Trusted Publisher settings – Verify the PyPI project settings include the Trusted Publisher entry that matches the repository, workflow file, tag pattern, and GitHub environment used by the publish workflow.
Verify release environment – Ensure the release environment can push tags to origin/main and has a GitHub token (for GitHub API operations like creating releases and fetching workflow runs). Missing requirements are reported with instructions before the publish step continues. In GitHub Actions, map a GitHub token into GITHUB_TOKEN/GH_TOKEN so the release tools can read it.
Export artifacts and push release tag – Uploads the built wheel/sdist artifacts to the GitHub release for the version tag and pushes the tag to GitHub. The publish.yml workflow listens for tag pushes and publishes to PyPI via OIDC.
Wait for GitHub Actions publish – The workflow pauses until the publish workflow completes, logging the GitHub Actions run URL when available so operators can monitor progress.
Record publish URLs & update fixtures – After the GitHub Actions publish completes (and the release is visible on PyPI), the workflow records the PyPI/GitHub URLs, updates fixtures, and commits the publish metadata.
Capture PyPI publish logs – Downloads the GitHub Actions publish run logs, stores the PyPI upload results, and persists them into the release fixtures for traceability.
