How a version of molochai-cli gets from main to a GitHub release and to PyPI. This is for
maintainers; contributors do not need any of it.
The CLI depends on the SDK through a direct reference:
dependencies = ["molochai @ git+https://github.com/Moloch-AI/uncensored-ai-python@v0.1.1"]That keeps pipx install "git+https://github.com/Moloch-AI/uncensored-ai-cli@v0.1.0" and
installs from main working while the SDK is not on PyPI. PyPI rejects any upload whose
metadata contains a direct reference, so the CLI can go to PyPI only after the SDK is there and
the dependency has been switched to molochai>=0.1.2,<0.2 (see
Switching the SDK dependency to PyPI). Until then:
- the release workflow still builds, checks and attaches the files to GitHub releases;
- its
buildjob warns about the direct reference, and fails with an explanation if it is about to publish to PyPI (a published release withPUBLISH_TO_PYPIset totrue), so nothing is uploaded; - CI shows the same warning on every run of the build job.
.github/workflows/release.yml runs when a GitHub release is published. It never runs on a push or a tag alone.
| Job | Runs when | Permissions | What it does |
|---|---|---|---|
build |
always | contents: read |
Builds the sdist and wheel, runs twine check --strict, runs .github/scripts/check_dist.py (one wheel and one sdist with the same version, tag v<version>, no direct references when publishing to PyPI), installs the wheel into a fresh virtual environment and runs molochai --version and molochai --help. |
github-release |
a release was published | contents: write |
Attaches the sdist and wheel to the GitHub release, so downloads are counted there too. |
pypi |
a release was published and the repository variable PUBLISH_TO_PYPI is true |
id-token: write, environment pypi |
Publishes the same files to PyPI with Trusted Publishing (no token is stored anywhere). |
verify-pypi |
after pypi |
none | Installs molochai-cli==<version> from PyPI into a fresh virtual environment and runs molochai --version. Retries for about five minutes while the index catches up. |
Each job runs only after the previous one succeeded, so nothing reaches PyPI unless the checks
passed and the files are on the GitHub release. If PUBLISH_TO_PYPI is not true, a release is
attached to GitHub only and the run says so in a notice.
Started by hand (Actions, "Release", "Run workflow"), the workflow is a dry run: it builds and checks, uploads nothing, and skips the tag check unless it was started from a tag.
- The SDK first.
molochaiis released to PyPI fromuncensored-ai-python(its RELEASING.md; the first upload is planned as 0.1.3, because 0.1.2 went to GitHub only). Itsverify-pypijob must have passed. - Then this CLI: switch the dependency, release 0.1.1, the first version on PyPI.
Do not set PUBLISH_TO_PYPI in this repository before the switch is merged. If it is set
early, a release fails in the build job with an explanation and nothing is uploaded.
Do this once, as version 0.1.1, after step 1 above.
-
Check that the SDK is installable from PyPI:
python -m pip download --no-deps --dest /tmp/molochai-check "molochai>=0.1.2,<0.2" -
On a branch from
main, editpyproject.toml:-
Replace the three comment lines above
dependenciesand the dependency itself with:dependencies = ["molochai>=0.1.2,<0.2"]
-
Delete the whole
[tool.hatch.metadata]table (its header, its comment andallow-direct-references = true). Without it, hatchling refuses to build if a direct reference ever comes back.
-
-
In
src/molochai_cli/_version.py, set__version__ = "0.1.1". -
In
CHANGELOG.md, turn## [Unreleased]into## [0.1.1] - YYYY-MM-DDwith the release date. Replace the "Planned for 0.1.1" paragraph with what this release is, for example:The first version on PyPI (`pipx install molochai-cli`). The CLI's code is unchanged. ### Changed - The SDK dependency is `molochai>=0.1.2,<0.2` from PyPI instead of the SDK's `v0.1.1` git tag, so installing the CLI no longer needs `git`.
At the bottom, replace the
[Unreleased]link with[0.1.1]: https://github.com/Moloch-AI/uncensored-ai-cli/compare/v0.1.0...v0.1.1. -
Update the documentation that mentions the git dependency:
README.md, Requirements: the SDK is "0.1.2 or newer, below 0.2 (installed automatically from PyPI)".README.md, Installation:pipx install molochai-cli,uv tool install molochai-cliandpip install molochai-clifirst; the GitHub tag (@v0.1.1) as the fallback; remove the sentence thatgitmust be available.CONTRIBUTING.md, Setup:gitis no longer needed..github/workflows/ci.ymland.github/workflows/live.yml: remove the comments about the SDK coming from a git tag and the check_dist warning.
-
Verify in a fresh virtual environment (
Scriptsinstead ofbinon Windows):python -m venv /tmp/cli-switch && . /tmp/cli-switch/bin/activate pip install -e ".[dev]" # now takes molochai from PyPI ruff check . && ruff format --check . && mypy && pytest rm -rf dist && python -m build && twine check --strict dist/* python .github/scripts/check_dist.py --tag v0.1.1 --for-pypi dist # no warning, exit 0 unzip -p dist/molochai_cli-0.1.1-py3-none-any.whl molochai_cli-0.1.1.dist-info/METADATA | grep "^Requires-Dist: molochai"
The last command prints
Requires-Dist: molochai<0.2,>=0.1.2. Then install the wheel into another fresh environment and runmolochai --version; it printsmolochai-cli 0.1.1 (molochai SDK 0.1.2, ...). -
Open a pull request, wait for CI, and merge.
-
Do the one-time setup below, then release
v0.1.1as described in Making a release (from step 5).
Do this once, shortly before the first PyPI release. Steps 1 and 2 can be done in either order.
A pending publisher lets the workflow create the molochai-cli project on its first upload.
-
Sign in at https://pypi.org with the account that will own the project (PyPI requires two-factor authentication).
-
Open your account menu, Publishing (https://pypi.org/manage/account/publishing/).
-
Under Add a new pending publisher, choose GitHub and enter exactly:
Field Value PyPI Project Name molochai-cliOwner Moloch-AIRepository name uncensored-ai-cliWorkflow name release.ymlEnvironment name pypi -
Click Add.
A pending publisher does not reserve the name: if someone else registers molochai-cli before
the first upload, it stops working. Make the first release soon after adding it. After the first
upload it turns into a normal trusted publisher, listed under the project's Manage,
Publishing page.
In the Moloch-AI/uncensored-ai-cli repository settings:
- Environments, New environment, name
pypi. Recommended protection:- Required reviewers: yourself, so every upload to PyPI waits for your approval.
- Deployment branches and tags: Selected branches and tags, add a rule of type
Tag with the pattern
v*.
- After the switch is merged: Secrets and variables, Actions, Variables tab,
New repository variable: name
PUBLISH_TO_PYPI, valuetrue. Without it (or with any other value), releases go to GitHub only. - Optional, for the weekly live tests (see CONTRIBUTING.md): Secrets
tab, New repository secret
MOLOCHAI_API_KEY, with a key from an account that holds only a small amount of credit (keys are not scoped).
Replace X.Y.Z with the new version.
-
On
main, set the version insrc/molochai_cli/_version.py. -
In
CHANGELOG.md, give the changes a## [X.Y.Z] - YYYY-MM-DDheading with the release date and add the compare link at the bottom. Update versioned commands inREADME.md(the@vX.Y.Zinstall commands). -
Run the checks from CONTRIBUTING.md, then:
python -m build twine check --strict dist/* python .github/scripts/check_dist.py --tag vX.Y.Z --for-pypi dist -
Commit, push to
main, and wait for CI to pass. -
Dry run: Actions, Release, Run workflow on
main. Thebuildjob must pass, without a "Not publishable to PyPI" warning if this release is meant for PyPI. -
Publish the release, from a clone of
main:awk '/^## \[X.Y.Z\]/{f=1; next} /^## \[/{f=0} f' CHANGELOG.md > /tmp/release-notes.md git tag -a vX.Y.Z -m "uncensored-ai-cli vX.Y.Z" git push origin vX.Y.Z gh release create vX.Y.Z --title vX.Y.Z --notes-file /tmp/release-notes.md --verify-tag
Creating the release on the GitHub website (tag
vX.Y.Zonmain, then Publish release) works the same. A pre-release also triggers the workflow and also goes to PyPI. A draft does not trigger it until it is published. -
Watch the run under Actions, Release. Approve the
pypideployment if you set required reviewers. -
Check https://pypi.org/project/molochai-cli/: the README renders and its links open the files on GitHub.
pipx install molochai-clithenmolochai --versionshows the new version.
buildfails (tag and version differ, a direct reference while publishing to PyPI, the smoke test): nothing was uploaded. Delete the release and its tag (gh release delete vX.Y.Z --cleanup-tag), fixmain, and release again.github-releaseorpypifails: fix the cause, then Re-run failed jobs on the same run; the files built bybuildare reused. For PyPI the usual cause is a publisher that does not match exactly: ownerMoloch-AI, repositoryuncensored-ai-cli, workflowrelease.yml, environmentpypi.- A broken version reached PyPI: PyPI never accepts the same file name twice, even after a deletion. Yank the version on pypi.org (the project's Manage, Releases page) and release the next patch version.