Releasing
A release is cut by two maintainer-dispatched runs of release.yml: the first
opens a release pull request, the second tags and publishes after it merges.
The workflow never runs on a push or a merged pull request, so merging cannot
publish an artifact by itself. main is protected with no bypass actors, so
the version bump lands through a pull request like any other change. The three
release artifacts keep separate tag namespaces so they never contend for the
same GitHub Release; the docs site piggybacks on the v<version> release and
has no tag of its own.
| Artifact | Workflow | Trigger | Release tag |
|---|---|---|---|
Unified Python wheel (kontext_studio-<version>-py3-none-any.whl) |
publish-pypi.yml |
dispatched by release.yml, or workflow_dispatch |
v<version> (GitHub Release + PyPI) |
@kontext-tech/* TypeScript packages (GitHub Packages) |
publish-ts-packages.yml |
push: tags: ["ts-packages-v*"] |
ts-packages-v<version> |
Docs site (docs.kontext.tech) |
publish-docs.yml |
workflow_call from release.yml, or workflow_dispatch |
none |
Cut a release
Section titled “Cut a release”Dispatch release.yml from main with:
| Input | Meaning |
|---|---|
bump |
auto (Commitizen reads the Conventional Commits), or force patch/minor/major. Ignored when version is set. |
version |
Release an already-tagged version without bumping. Used to resume. |
publish_pypi |
Dispatch publish-pypi.yml once the Release exists (default true). |
publish_docs |
Publish the docs site (default true). |
prerelease |
Mark the GitHub Release as a prerelease. |
1. Open the release pull request
Section titled “1. Open the release pull request”The first dispatch with an empty version input:
- Checks out
origin/main, requiressecrets.PAT_FOR_TAG_PUSH(see below), and runsvalidate:workspace-versions. - Runs
cz bump. It rewrites everyversion_filesentry, prependsCHANGELOG.md, and creates thechore(release): version <old> -> <new>commit. The workflow drops the local tag, pushes arelease/v<new>branch, and opens a pull request titledchore(release): version <new>with the generated release notes in its body. - Stops there. The
release,publish-docs, andpublish-pypijobs are skipped until the PR merges. - Approve and Squash and merge the PR. The ruleset only allows squash merges.
2. Tag and publish
Section titled “2. Tag and publish”Re-dispatch release.yml from main with version=<new> (bump is ignored).
This run:
- Validates that
package.jsononmainis already at<new>. - Creates and pushes
ts-packages-v<new>, which publishes the@kontext-tech/*packages. - Creates or promotes the
v<new>GitHub Release at the merge commit, using the changelog section as the release notes. - Publishes the docs site (unless
publish_docsis false). - Dispatches
publish-pypi.ymlwithtarget=pypi,version, andconfirm(unlesspublish_pypiis false). It stays a top-level workflow because PyPI trusted publishing does not support reusable workflows.
publish-pypi.yml refuses a production publish when version differs from the
workspace version or confirm differs from version, so a typo fails the run
instead of publishing the wrong artifact.
PAT_FOR_TAG_PUSH must carry contents:write (to push the release branch and
tags), pull_requests:write (to open the release pull request), and
actions:write (to dispatch publish-pypi.yml). The workflow GITHUB_TOKEN
cannot open a cross-workflow PR here, and pushes it makes do not start other
workflows.
Resume a partial release
Section titled “Resume a partial release”Publishing is the only stage that can fail after the version is immutable. Re-dispatch the failed workflow directly:
- Release PR is open but not merged — approve and squash-merge it, then
re-dispatch
release.ymlwithversion=<version>. - PyPI failed — dispatch
publish-pypi.ymlwithtarget=pypi,version, andconfirm. - Docs failed — dispatch
publish-docs.yml. - Tag pushed but the GitHub Release was never created — re-dispatch
release.ymlwithversion=<version>; it skips the bump.
Docs site
Section titled “Docs site”release.yml calls the reusable publish-docs.yml workflow when publish_docs
is true (the default). The workflow builds docs-site/dist, syncs it to the S3
bucket behind docs.kontext.tech, invalidates CloudFront, and smoke-tests the
distribution. Dispatch publish-docs.yml directly for a docs-only change.
It needs the AWS_DEPLOYMENT_ROLE_ARN_GLOBAL secret and the production
environment. The S3 bucket, distribution, and Route53 record are defined in
kontext-tech/kontext-platform as DocsCloudFrontStack.
TestPyPI
Section titled “TestPyPI”Dispatch publish-pypi.yml with target=testpypi. It derives a
<version>.dev<run><attempt> version so repeat uploads do not collide,
publishes, then reinstalls from TestPyPI and runs kontext --help.
Both indexes authenticate with PyPI trusted publishing (OIDC); no API token is
stored. The upload job must stay in this top-level workflow because PyPI does
not support reusable workflows as a trusted publisher. Both pending publishers
name publish-pypi.yml and use the matching testpypi / pypi environment;
both environments only allow deployments from main.
Releasing the TypeScript packages
Section titled “Releasing the TypeScript packages”The @kontext-tech/* TypeScript packages are versioned in lockstep with
Commitizen, configured under
[tool.commitizen] in the root pyproject.toml. There is no release PR step:
release.yml produces the bump, changelog, commit, and tag in one action, and
pushing the tag publishes.
Bump and tag
Section titled “Bump and tag”release.yml runs uv run cz bump for you. To do the same locally:
pnpm run version:labsgit push --follow-tagsDo not use both paths for one release: release.yml always starts from
origin/main, so a local bump must be pushed before dispatching it.
That runs uv run cz bump, which:
- Reads the Conventional Commits since the last
ts-packages-v*tag. - Computes the next version and rewrites
versionin everyts/*/package.jsonandpy/*/pyproject.tomlfile, the rootpackage.json, andapp/package.json(theversion_fileslist). The root version is not cosmetic:scripts/build-app-image.shreads it asPUBLIC_KONTEXT_VERSION. - Prepends the release notes to the root
CHANGELOG.md. - Creates the
chore(release): version <old> -> <new>commit and thets-packages-v<new>tag.
Preview without changing anything:
uv run cz bump --dry-run --yesBecause major_version_zero = true, breaking changes still bump the minor
version while the project is pre-1.0. Force a specific increment when needed:
uv run cz bump --patch # or --minor / --major / --prereleaseVerify lockstep before publishing
Section titled “Verify lockstep before publishing”pnpm run validate:workspace-versionstools/validate-workspace-versions.mjs asserts that every package in the
ts/* workspace and the py/* workspace carries the same version, that the
root package.json and [tool.commitizen] agree with it, and that every package
is registered in version_files. It catches the one failure Commitizen cannot: a
version edited by hand, or a new ts/*/py/* package that was never added to
version_files (and so would be published unpinned). Pre-commit, CI, and the
publish workflow all run it, and the publish workflow additionally fails if the
pushed tag does not equal ts-packages-v<root package.json version>.
Both workspaces share the single ts-packages-v$version tag and the one
[tool.commitizen] version. ts/schema owns the OpenAPI contract and the
generated TypeScript API types, so both must always match the library version;
registering py/* in version_files is what keeps the Python distributions in
lockstep too.
Legacy tags
Section titled “Legacy tags”Earlier releases used one tag per package (@kontext-tech/<name>@<version>), and
those tags anchor the published GitHub Releases from that era. They are frozen
history: the lockstep scheme deliberately replaced them with the single
ts-packages-v<version> tag, so they are no longer read by the release tooling.
Commitizen logs one Invalid version tag warning per legacy tag on every
changelog run because they do not match tag_format. The warnings are cosmetic —
cz bump resolves the last release from ts-packages-v* only — but they are
expected, not a signal that something is misconfigured.
Do not delete or retag the legacy tags without deciding what should happen to
the GitHub Releases they anchor. git push --delete is refused for a tag that
backs a published release, and one of them is the repository’s current “Latest”
release.
Publish
Section titled “Publish”publish-ts-packages.yml triggers on ts-packages-v* — pushed by
release.yml or by git push --follow-tags — builds the shared packages, and
runs pnpm --filter "./ts/*" publish against npm.pkg.github.com.
The packages publish under the @kontext-tech scope, matching the repository
owner, so publish-ts-packages.yml uses the workflow GITHUB_TOKEN with
packages: write and needs no PAT. Consumers outside the org still need a
token with read:packages access.
Commitizen replaces the previous Changesets flow. The package versions were
normalized to a single lockstep version before the switch, because Commitizen
reads one configured version and writes it to every entry in version_files.
Commit message format is enforced on push by
scripts/check-commitizen-branch.sh, which runs uv run cz check over the
commits ahead of the base ref (see .pre-commit-config.yaml).