kaizen-agentic/docs/PACKAGE_RELEASE.md

Python Package Release

kaizen-agentic publishes as the kaizen-agentic Python package on the Forgejo PyPI registry. Public pypi.org distribution is optional and not required for ecosystem use.

Install (consumers)

Dependencies such as pyyaml resolve from public PyPI. Use Forgejo as an extra index:

pip install kaizen-agentic \
  --extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/

Global CLI via pipx:

pipx install kaizen-agentic \
  --pip-args="--extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/"

Consumer reads are anonymous. Keep publish credentials in Forgejo Actions secrets or inject them through the environment for a deliberate local release.

Local Release

Build and validate artifacts:

make package-check

Publish to the Coulomb organization registry:

TWINE_USERNAME=<forgejo-user> \
TWINE_PASSWORD=<package-token> \
make publish-forgejo

Package upload endpoint:

https://forgejo.coulomb.social/api/packages/coulomb/pypi

Consumer simple index:

https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/

Forgejo repository secrets (one-time)

Configure in Forgejo: Repository → Settings → Actions → Secrets (or use organization-level secrets when managed centrally).

Secret	Value
FORGEJO_PYPI_USER	Forgejo username that owns the package token
FORGEJO_PYPI_TOKEN	Forgejo token with package-write permission

Discover credential ownership before requesting or rotating a token:

warden route find "publish kaizen-agentic to Forgejo PyPI" --json

Never commit or copy the token into documentation, workplans, or State Hub.

The publish workflow fails at the upload step when either secret is missing or invalid. Do not commit tokens to the repository.

Verified (2026-08-20): the Forgejo index serves kaizen-agentic==1.4.0. A fresh virtual environment installed it with --no-cache-dir and the CLI reported version 1.4.0.

Verify secrets without cutting a release:

1. Open Actions → Publish Python package → Run workflow (workflow_dispatch), or dispatch via API: POST /api/v1/repos/coulomb/kaizen-agentic/actions/workflows/publish-python-package.yml/dispatches with body {"ref":"main"}
2. Confirm the run completes and twine upload succeeds
3. Optional: pip install kaizen-agentic==<version> --extra-index-url ...

The publish job uses an isolated .build-venv on the runner (PEP 668 safe).

Pre-tag release checklist

Before git tag vX.Y.Z && git push origin vX.Y.Z:

• make release-check passes (tests, flake8, version consistency, agent parity)
• make package-check builds and validates dist/*
• CHANGELOG.md has a dated [X.Y.Z] section matching pyproject.toml
• FORGEJO_PYPI_USER and FORGEJO_PYPI_TOKEN secrets are set
• Publish workflow smoke-tested via workflow_dispatch (or prior tag release)
• make agents-sync-package run if agents/ changed since last release

Forgejo Actions Release

The .forgejo/workflows/publish-python-package.yml workflow publishes on tags matching v*.

Example:

git tag v1.2.0
git push origin v1.2.0

Public PyPI (optional)

When pypi.org credentials are configured (~/.pypirc or TWINE_PASSWORD API token with TWINE_USERNAME=__token__):

make release-publish
python -m twine upload dist/*

Scheduled-run runner prerequisites (WP-0006)

A runner that executes a scheduled kaizen agent task (fired by activity-core) needs:

• kaizen-agentic on PATH — pip install kaizen-agentic (or pipx install kaizen-agentic) using the Forgejo PyPI extra index when installing from the internal registry:

  pip install kaizen-agentic \
    --extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/
  

• Repo checkout reachable at the host_paths[<host>] registered in State Hub, with a valid .kaizen/schedule.yml (kaizen-agentic schedule validate).
• No State Hub required for prepare — schedule prepare reads local .kaizen/ state only. The hub is needed by the resolver (activity-core), not by the prepared session.

Enabling a definition (activity-core operator): keep the kaizen definitions at enabled: false until a manual smoke test passes (see INTEGRATION_PATTERNS.md Pattern 2 and the activity-core handoff checklist), then flip one definition to enabled: true in staging before fleet-wide enable.