CIRCLE
Project

Release channels

How versions of auth-ai reach PyPI: stable releases, pre-releases and nightly developmental releases, with PyPI Trusted Publishing.

The package is published to PyPI as auth-ai under the MIT license, and imported as auth_ai. It requires Python 3.12 or later.

Channels

ChannelTriggerPyPI versionInstall
StableCreating a GitHub release vX.Y.Z from main.X.Y.Zpip install auth-ai
Pre-releaseCreating a GitHub release marked pre-release for a version such as X.Y.ZrcN.X.Y.ZrcNpip install --pre auth-ai
NightlyA manual run of the Nightly workflow, from develop or main.X.Y.Z.devYYYYMMDDHHMMpip install --pre auth-ai

pip skips pre-releases and developmental releases unless you pass --pre (or pin the exact version).

Stable

The release is the trigger: create the GitHub release (and its tag vX.Y.Z) from main once the version is set in pyproject.toml. The workflow never creates a release or a tag itself. It:

  1. runs the same quality gates as continuous integration (format check, lint, strict type-check, unit tests with a coverage threshold, build and distribution checks, and an audit of the runtime dependencies);
  2. requires that the tag matches the version in pyproject.toml, that the pre-release flag of the release matches the version (a PEP 440 a, b, rc or .dev suffix means pre-release), and that a stable release points at a commit on main;
  3. builds the wheel and the source distribution, checks them with twine check --strict, and publishes them.

If a run fails, fix the cause, then delete the release and its tag and create them again. PyPI never accepts the same version twice: bump the version if one was already uploaded.

Nightly

A nightly is published as a PEP 440 developmental release X.Y.Z.devYYYYMMDDHHMM, where the suffix is the UTC date and minute of the run. X.Y.Z is the version in pyproject.toml, or the next patch when that version is already on PyPI, so a nightly never sorts before a stable release. The version exists only in the workflow's workspace: no commit is made, so no version bump lands on the branch. The nightly runs the same quality gates first.

Use a nightly to try an unreleased change. Nothing about its API is guaranteed. Nightlies stay on PyPI: removing or yanking one is a manual action on pypi.org, because Trusted Publishing covers uploads only.

Authentication to PyPI

Both workflows publish through PyPI Trusted Publishing (OpenID Connect): no PyPI token is stored in the repository. Each workflow file (release.yml, nightly.yml) must be registered as a trusted publisher of the auth-ai project on pypi.org (owner circle-rd, repository auth-ai-py, GitHub environment pypi); before the first upload, register them as pending publishers.

Versioning

The project follows Semantic Versioning, written as a PEP 440 version. While the major version is 0, a breaking change bumps the minor version. Breaking changes are listed in the changelog, with a migration note, and the old behaviour is removed rather than kept behind a compatibility shim.

Supported runtimes and dependencies

Continuous integration runs the checks on Python 3.12, 3.13 and 3.14. Newer interpreters (3.15) are tested too, but without blocking a release. The runtime dependencies are httpx2[brotli,http2] (>=2.16), joserfc (>=1.7) and pydantic (>=2.12); the fastapi (>=0.115) and starlette (>=0.46) extras are optional.

Copyright © 2026