145 lines
4.6 KiB
Markdown
145 lines
4.6 KiB
Markdown
# Python Package Release
|
|
|
|
`kaizen-agentic` publishes as the `kaizen-agentic` Python package on the Forgejo
|
|
PyPI registry. Public [pypi.org](https://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:
|
|
|
|
```bash
|
|
pip install kaizen-agentic \
|
|
--extra-index-url https://forgejo.coulomb.social/api/packages/coulomb/pypi/simple/
|
|
```
|
|
|
|
Global CLI via pipx:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
make package-check
|
|
```
|
|
|
|
Publish to the Coulomb organization registry:
|
|
|
|
```bash
|
|
TWINE_USERNAME=<forgejo-user> \
|
|
TWINE_PASSWORD=<package-token> \
|
|
make publish-forgejo
|
|
```
|
|
|
|
Package upload endpoint:
|
|
|
|
```text
|
|
https://forgejo.coulomb.social/api/packages/coulomb/pypi
|
|
```
|
|
|
|
Consumer simple index:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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__`):
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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](INTEGRATION_PATTERNS.md) and the
|
|
[activity-core handoff checklist](integrations/activity-core-handoff-wp0006.md)),
|
|
then flip one definition to `enabled: true` in staging before fleet-wide enable.
|