Releasing¶
Work lands on develop; main holds what is released and changes only through a pull request from develop (or a
hotfix/... branch). A release is a tag vX.Y.Z on main. .github/workflows/release.yml then runs every gate
(the CI workflow) and publishes:
| What | Where | How |
|---|---|---|
The service image, lite and full, linux/amd64 and linux/arm64 |
ghcr.io/giordyfish/evokai:X.Y.Z (and latest), ghcr.io/giordyfish/evokai:X.Y.Z-full |
GITHUB_TOKEN, signed keyless with cosign (scripts/sign-image.sh), with build provenance and an SBOM attestation |
The Python client evokai-client |
PyPI | trusted publishing (OpenID Connect): no token in the repository |
@evokai/evokai-client and @evokai/evokai-ui |
npm | npm publish --provenance with the NPM_TOKEN secret |
The aliases evokai on PyPI (installs evokai-client) and evokai on npm (re-exports @evokai/evokai-client) |
PyPI and npm | as above (clients/aliases) |
The service itself is distributed as the image, not on PyPI: its migrations (migrations/, alembic.ini) and the
built console (admin/dist) live outside the Python package, so a wheel of it would not run on its own. The capability
worker (workers/capability) is built from its own Dockerfile and is not published by this workflow.
A tag with a suffix (v0.2.0-rc.1) is a pre-release: the image gets no latest tag and npm gets the next
dist-tag.
Cutting a release¶
- Set the same version everywhere:
pyproject.toml,clients/python/pyproject.toml,workers/capability/pyproject.toml,clients/typescript/package.json,clients/ui/package.json(its version and its peer dependency on@evokai/evokai-client),admin/package.json, and the aliases inclients/aliases(their versions and their dependency on the client). Refresh the lockfiles (uv lock,uv lockinclients/pythonandworkers/capability,npm install --package-lock-onlyin the three npm folders). The workflow's first job refuses a tag that does not match. - Move the entries under Unreleased in CHANGELOG.md to a new section with the version and the date.
- Run
scripts/ci.sh, commit todevelop, then open a pull request fromdeveloptomainand merge it when CI is green. - Tag and push the tag:
git tag -s vX.Y.Z -m "Evokai X.Y.Z" && git push origin vX.Y.Z. - When the workflow is green, create the GitHub release from the tag with the changelog section as its notes.
One-time setup¶
GitHub repository¶
- Settings, Actions, General, Workflow permissions: read-only
GITHUB_TOKENis enough; the jobs ask for what they need (packages: write,id-token: write). - Settings, Environments: create
pypi,pypi-aliasandnpm. Restrict all three to tags matchingv*(deployment branches and tags), and add yourself as a required reviewer if every publish should wait for a click. - Settings, Code security: enable private vulnerability reporting (it is how SECURITY.md and the code of conduct receive reports), Dependabot alerts and secret scanning.
- Rulesets:
maintakes changes only through a pull request with the CI checks green (no direct push, no force push, no deletion; the check Pull request source refuses any branch other thandeveloporhotfix/...);developtakes pull requests with the CI checks green, and the maintainer may push to it directly. For the DCO sign-off to be enforced too, add the DCO GitHub App. - The actions in both workflows are pinned to commit SHAs; Dependabot (
.github/dependabot.yml) keeps them current, and the CI job Workflow security runs zizmor on every change.
GitHub Container Registry¶
The first push creates the package ghcr.io/giordyfish/evokai, private by default. Then, in the package's settings:
- Change visibility to public, so the image can be pulled without a login;
- Manage Actions access: make sure the
Giordyfish/evokairepository has the Write role (it has it when the package was created by its workflow, which links them).
Verify a released image with the keyless command in deployment.
PyPI (trusted publishing)¶
No API token is stored anywhere. On PyPI, signed in as the owner:
- Your account, Publishing, Add a new pending publisher (the project does not exist before the first release).
- PyPI project name
evokai-client; ownerGiordyfish; repositoryevokai; workflow namerelease.yml; environmentpypi. - Add a second pending publisher for the PyPI project name
evokai(the alias), the same except the environment:pypi-alias(PyPI refuses two pending publishers with the same repository, workflow and environment). - The first tag creates both projects. Afterwards each publisher shows under its project's Publishing settings.
Optionally do the same on TestPyPI and try a pre-release tag there first (change the publish step's
repository-url for that run).
npm (trusted publishing)¶
No npm token is stored anywhere: the release job proves its identity to npm over OpenID Connect (npm 11.5.1 or newer) and gets a short-lived token for the publish.
- Create the
evokaiorganisation on npmjs.com (free for public packages), so the@evokaiscope belongs to you, and enable two-factor authentication on your account. - A package must exist before it can name a trusted publisher, so the very first release of a new package goes out
with a granular access token (read and write on all packages, allowed to bypass two-factor authentication for
publishing), stored as the secret
NPM_TOKENof thenpmenvironment and passed asNODE_AUTH_TOKENto the publish step. - Then, on npmjs.com, for each package (
@evokai/evokai-client,@evokai/evokai-ui,evokai): Settings, Trusted publishing, GitHub Actions, with organisation or userGiordyfish, repositoryevokai, workflowrelease.ymland environmentnpm. Under Allowed actions allow publish (the workflow publishes directly) and leave dist-tag off. Optionally set Publishing access to require two-factor authentication and disallow tokens. (Allowing only staging is stricter: the workflow would then runnpm stage publishand every version would wait for a maintainer's approval with two-factor authentication.) - Delete the token on npmjs.com and the
NPM_TOKENsecret on GitHub.
The packages carry publishConfig.access: public; --provenance links each published version to the workflow run
that built it (shown on its npm page).