Publishing releases

Releases use the manually dispatched .github/workflows/publish.yml workflow on main. It requires successful CI for the same commit, verifies the requested version against pyproject.toml, builds distributions, and runs the AF3 example from isolated wheel and source-distribution installs. A separate job downloads those exact artifacts and publishes them through PyPI Trusted Publishing.

One-time setup

In the project’s PyPI publishing settings, register a GitHub publisher with these exact values:

Field

Value

Owner

nimashoghi

Repository

nshconfig

Workflow filename

publish.yml

Environment

pypi

The GitHub pypi environment allows deployments from the main branch. Only the upload job has id-token: write; no long-lived PyPI token is stored in GitHub. The workflow filename and environment must match the registration on PyPI. See PyPI’s setup documentation.

Release procedure

  1. Commit the intended package version and lockfile, review the PR, and merge it to main.

  2. Wait for the main-branch CI run to pass. Local release validation remains available through ./scripts/publish.sh --dry-run --trusted-publishing never.

  3. Dispatch the workflow with the exact version:

    gh workflow run publish.yml --repo nimashoghi/nshconfig --ref main -f version=3.0.0a0

  4. Check the workflow result and verify the release on PyPI. The dist workflow artifact contains the distributions that were uploaded.

  5. Create the corresponding version tag/GitHub release at that workflow’s source commit, using the uploaded distributions as release assets. Mark alpha/beta/rc versions as prereleases.

Dispatching from another branch skips publication. A failed CI/version check prevents the upload job from running. The workflow fails explicitly if the PyPI publisher is missing or mismatched. A new release requires a new version; published files cannot be overwritten.