Skip to content

Latest commit

 

History

History
177 lines (145 loc) · 9.21 KB

release.md

File metadata and controls

177 lines (145 loc) · 9.21 KB

Releases

Pitot publishes one release from a verified commit on main. A release contains:

  • native Linux and macOS archives for amd64 and arm64;
  • canonical ghcr.io/labstack/pitot:<version> and latest multi-architecture images;
  • byte-identical labstack/pitot:<version> and latest Docker Hub mirrors;
  • SHA-256 checksums and GitHub build-provenance attestations for every archive;
  • an io.github.labstack/pitot entry in the official MCP Registry;
  • the Apache-2.0 license, project notice, trademark policy, and generated third-party notices in every archive and container image.

Version contract

Tags use unpadded CalVer: vYYYY.M.N[-alpha|-beta|-rc]. The suffix states product maturity; GA has no suffix. The first release in a month is .0, and every release increments N regardless of suffix. Pitot is alpha. For example, v2026.10.1-alpha follows v2026.10.0-alpha. Container tags omit the leading v, so v2026.10.1-alpha publishes ghcr.io/labstack/pitot:2026.10.1-alpha and labstack/pitot:2026.10.1-alpha. Every release moves latest. GitHub Releases are not marked as prereleases: the tag carries maturity, and the installer's /releases/latest must resolve. Only release and latest tags are mirrored to Docker Hub; main and commit tags remain GHCR-only.

Deployments should resolve public tags to immutable registry digests. Keep live manifests and secret profiles outside this public repository.

A tag without a suffix is a stable release; -alpha, -beta and -rc tags are prereleases. Because latest follows both, it is not a stable channel. The upgrade policy, published at https://pitot.dev/docs/guides/upgrade, sets the notice period for breaking changes, the route and API deprecation rules, and the same-version restore requirement.

Upgrade notes

Every release's notes start with an Upgrade notes section that scripts/release-notes.sh writes during the tag workflow's verify job, before anything is published. It compares the tag with the previous published, non-draft GitHub Release, which the workflow lists with gh release list. A tag whose workflow failed has no release and is skipped, so the next published release reports its changes. The section marks:

  • a batch format change, read from batchMetadataVersion in internal/telemetry/parquet.go, as a Format change caution: the release cannot read earlier telemetry;
  • control migrations added under internal/db/migrations, which run forward at startup, as a Control schema migration;
  • otherwise, a Storage line stating that neither changed;
  • merged changes whose titles carry the Conventional Commits ! marker, under Breaking changes.

The script fails the release when it cannot read the format version, so a format change is never published unmarked. just release-test covers it. The section is prepended to GitHub's generated changelog; maintainers add manual upgrade steps and deprecation notices below it. A format-changing or breaking pull request should say so in its title with ! and describe the operator steps in its description, so they can be copied into the notes.

Creating a release

Run just release from a clean, current main. The script:

  1. verifies that no other release is running;
  2. waits for CI's push run on main for that commit, which runs every check and the race-enabled Go suite, and stops unless it passed;
  3. confirms that neither local HEAD nor origin/main moved meanwhile;
  4. calculates and pushes the next CalVer tag.

The tag workflow then independently validates tag syntax, ancestry, and ordering. It reuses that CI result for the tagged commit, re-running only the dependency audit, and runs the full suites itself when no successful run exists. It then builds every target on its native runner; publishes the multi-architecture image; copies that accepted manifest to Docker Hub; requires the registry digests to match; and creates the GitHub release only after anonymous pulls from both GHCR and Docker Hub succeed. A final job downloads every release asset without credentials, verifies checksums, inspects the legal payload, exercises the installer, and verifies provenance. Only after those checks pass does the workflow publish the release's server.json to the MCP Registry with GitHub OIDC; no long-lived registry credential is stored in the repository.

The release workflow builds CGO targets on four native runners. It creates archives, checksums and attestations, then verifies the published artifacts.

Consumer verification

The installer verifies SHA256SUMS before extraction. A downloaded archive can also be verified directly:

sha256sum -c SHA256SUMS
gh attestation verify pitot_v2026.10.1-alpha_linux_amd64.tar.gz \
  --repo labstack/pitot

For containers, pin or record the digest returned by the registry:

docker buildx imagetools inspect ghcr.io/labstack/pitot:2026.10.1-alpha
docker buildx imagetools inspect docker.io/labstack/pitot:2026.10.1-alpha

Supply-chain scope

The release workflow uses SHA-pinned Actions, archive checksums, GitHub build provenance, dependency and secret scanning, legal inventories, and post-publication verification. The container is consumed by immutable digest.

Standalone signatures and SBOMs are outside the release artifact inventory. GitHub build provenance identifies the source; THIRD_PARTY_NOTICES lists the shipped dependencies.

First Pitot release

After merging the rename pull request:

  1. Verify the GitHub repository is labstack/pitot. Update remotes and the repository website to https://pitot.dev; configure that domain for the site deployment. Configure the pitot Cloudflare Pages project used by site.yml and migrate the media hostname to assets.pitot.dev before enabling the renamed site workflow. All six landing stills and site/public/logo.svg are generated by just landing-captures (see below). Verify hosted clips separately. The social card and favicons are unchanged.

  2. Verify the renamed repository's Actions permissions, branch protection, environments, OIDC trust and package access. Ensure ghcr.io/labstack/pitot is public and Actions can write it. Create or configure the public Docker Hub labstack/pitot image destination and retain the workflow's existing credential delivery. Do not overwrite old releases or image tags.

  3. Wait for the merged main CI run to pass, then run just release from a clean, current main. This selects the next unused vYYYY.M.N-alpha tag; do not reset the monthly sequence because the product changed names.

  4. Wait for the tag-triggered release.yml workflow, including anonymous image pulls, pitot_ archives containing ./pitot, checksums, attestations and installer verification. It publishes version and latest images to both new image destinations. Add the rename and upgrade notice from CHANGELOG.md to the release notes.

  5. The final workflow job authenticates with GitHub OIDC and publishes the tagged server.json as io.github.labstack/pitot in the MCP Registry. Verify that entry and its version after the job passes; retire the old registry listing separately according to registry policy. Do not publish from this branch.

  6. Verify the upgrade steps in CHANGELOG.md, including the control database filename, session cookies and saved chat metadata. Telemetry footer keys use the pitot.spill. namespace. The pre-rename environment variable prefix is no longer read.

Refresh landing stills

Run just landing-captures with the locked browser dependencies and Google Chrome installed. It builds the current app and seed command, starts an isolated loopback-only instance, and stops it after capture. No private instance, API key, or LLM provider is used; inherited external capture settings are cleared.

The checked-in landing seed generates a dense hour across fourteen fictional store services: about 39 requests/s, 0.01% errors, 50 ms p95 and 21 error logs. The seed is deterministic for its seed and minute-aligned end time. Its reported window freezes the UI clock for both themes. landing-dashboard.json is saved through the real dashboard API and all stats/series use real telemetry queries. The fixed landing-chat.json transcript loads through the real chat UI and MCP App renderer; only the saved-thread reads and the UI capability flag are fixtures. External browser requests and model runs are blocked and fail the capture.

All screenshots retain the full header, expanded sidebar and content at a 1280×800 CSS viewport. overview-{light,dark}.png use 1.5× scale (1920×1200, the original README hero dimensions); dashboard-{light,dark}.png and chat-{light,dark}.png use CSS scale (1280×800). The overview and dashboard images show Store overview - last hour, including the four stats and request rate, error rate and p95 latency by service. The logo is exported from the rendered app BrandLockup/mark, with the site's display font stack.

Before committing, view every image in both themes and OCR the header when Tesseract is available. Confirm PITOT, an expanded sidebar, populated charts, a healthy error-rate stat and no loaders or old wordmark. Favicons and the social card are separate artifacts and are not regenerated by this recipe.