> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apowerb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Release process

> How the Python package and the TypeScript SDK are published.

## Python — PyPI

`apowerb` is published to [PyPI](https://pypi.org/project/apowerb/) from GitHub Actions
using **trusted publishing** (OIDC): the workflow authenticates as the repository
itself, so no long-lived API token is stored in the project.

The workflow lives in `.github/workflows/pypi-publish.yml` and runs on a release.

## npm — the TypeScript SDK

The SDK is published from GitHub Actions with npm **trusted publishing**, and the
resulting package carries a provenance attestation naming the repository, the workflow,
the tag and the runner.

> [!WARNING]
>
> Two things are easy to get wrong here:
>
> * npm refuses to declare a trusted publisher for a package that **does not exist
>   yet**. The very first publish has to happen another way; only then can trusted
>   publishing be configured. PyPI does not have this constraint.
> * `--provenance` does not work from a local machine. Provenance requires a hosted CI
>   runner.

## Documentation — before the deployment, not after

The hosting platform deploys this repository on its own, and `docs-live` checks that it
actually did: after every push to `main`, it looks for a word the commit just
wrote **on the served page**. It tests the result, not the mechanism.

> [!NOTE]
>
> Triggering the deployment from CI was the first design, and it does not work
> here: the platform's update API answers
> `401 {"error":"Please upgrade to access this route."}` on this plan. Checking
> the outcome turned out to be the better question anyway — it stays true
> whatever the plan, and it catches a deployment that silently did not happen.

Two guards keep the site from drifting behind what is actually deployed:

**1. apowerb-hosting refuses a change its documentation contradicts**

`docs-in-sync` reads `helm/apowerb-chart/Chart.yaml` and compares its name,
version and path with every OCI address and `--version` written in these
pages. A pull request that moves the chart fails until the matching docs
pull request exists — an **open** one is enough, it does not have to be
merged first.

**2. This repository proves the site caught up**

`docs-live` picks a word each changed page gained, then polls the live page
for up to ten minutes. A merge is not a publication, and a publication that
never lands has to be visible.

When it fails, look at the platform's project log first: an invalid page
stops the deployment, and that is the most common cause here — it is
exactly what happened on 8 September, when a `</Steps>` closed too early
made `mint validate` fail and three merges never went live.

> [!WARNING]
>
> On 8 September 2026 this site served, for an hour after the chart had moved
> to `apowerb/apowerb-chart` 0.4.1, the command it used to carry:
>
> `helm install apowerb oci://registry-1.docker.io/apowerb/apowerb --version 0.2.0`
>
> The reason it went unnoticed is worth remembering: **the stale command still
> worked**. The old chart is still pullable, so a reader got a silent,
> successful install of the stack from before th2etl, th2pulse, the persistent
> volume and 27 environment variables. No error, no red build, nothing to
> notice. That is what these guards exist to make impossible.

## Versioning

Versions follow [semantic versioning](https://semver.org/). The changelog is the
GitHub releases page of each repository.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.