Releases

A release is a GitHub release that holds one archive and one manifest per platform. Pushing a version tag starts .github/workflows/release.yml, which checks the tagged commit, builds every target and creates the release as a draft. You test the draft, publish it, and then publish the Python and Node packages by hand with the release’s digests in them. No workflow publishes to PyPI or npm.

Cut a release

Prepare the last commit

In the commit you will tag:

Set the new version in all five places: python/pyproject.toml, python/apostate/config.py, npm/package.json, npm/src/index.ts and .github/release/artifact-policy.json (package_version).
Refresh the patch digests in build/MANIFEST.lock. The command rewrites patch_series_sha256 and patch_contents_sha256 and nothing else, so run it after the last patch edit.
If the composed profiles changed, refresh the golden digests.

python3 scripts/validate-release-baseline.py --refresh
python3 scripts/sync-packages.py --check
python3 scripts/validate-release-baseline.py --release
APOSTATE_REQUIRE_NATIVE_GOLDENS=1 python3 scripts/test_profile_resolver.py

sync-packages.py --check fails and lists the five values while they differ:

package version differs between sites:
  python/pyproject.toml: 0.4.3
  python/apostate/config.py: 0.4.3
  npm/package.json: 0.4.4
  npm/src/index.ts: 0.4.3
  .github/release/artifact-policy.json: 0.4.3

Tag and push

Tag that commit vMAJOR.MINOR.PATCH and push the tag:

git tag -a v0.4.4 -m 'Apostate 0.4.4'
git push origin v0.4.4

Wait for the build

Each platform builds on its own runner, all at once, and takes hours. If one fails, re-run the failed jobs. The platforms that finished keep their artifacts for 7 days and are not rebuilt.

Test and publish the draft

Download the archives, launch each on its platform, and launch the Linux archives in a GPU-less container as well. Then publish the release:

gh release download v0.4.4 -D ./apostate-release
gh release edit v0.4.4 --draft=false

Publish the packages

Write the release’s digests into both packages, commit, and publish them (below).

The repository variable APOSTATE_BUILD_TARGETS, a comma-separated list such as macos-arm64,linux-x64, limits a release to those platforms. Unset, it means all four. To rebuild an existing tag, run the workflow by hand with that tag as release_tag and confirm set to true:

gh workflow run release.yml -f release_tag=v0.4.4 -f confirm=true

The macOS build signs and notarizes when the six APPLE_* repository secrets are set (Sign on macOS). Without them it publishes an unsigned macOS archive, and the job log says sign-macos: no signing identity configured; the bundle stays unsigned.

What CI checks

release.yml runs four jobs.

Release gate, on a hosted Ubuntu runner. The tag must match vMAJOR.MINOR.PATCH and name the checked-out commit. Then scripts/validate-release-baseline.py --release (the patch digests in build/MANIFEST.lock match the series), scripts/test_profile_resolver.py with APOSTATE_REQUIRE_NATIVE_GOLDENS=1, and the Python and Node package tests.
Setup resolves the platforms from APOSTATE_BUILD_TARGETS with scripts/resolve-build-targets.sh.
Build runs .github/workflows/build-target.yml once per platform: every step on Build from source from an empty workspace, the resolver and baseline checks again, scripts/smoke-binary.sh, signing on macOS, packaging, upload, and a GitHub build-provenance attestation for the archive.
Publish downloads every archive and manifest and runs scripts/verify-release-inputs.sh. It requires exactly one archive and one manifest per built platform, and checks each manifest’s field set, its package and Chromium versions against the release policy, its catalogue_version and source_revision against the tagged commit, and its sha256 against the archive. Then gh release create --verify-tag --draft creates the draft.

verify-release-inputs.sh also runs outside CI, on any directory of archive and manifest pairs, such as a nightly build’s artifacts. The second argument is the exact set of platforms the directory holds. Pass any as the revision to accept whatever commit the manifests name:

scripts/verify-release-inputs.sh ./artifacts linux-x64,macos-arm64 any

It prints verified <platform> <archive> for each pair and release inputs verified: <platforms> at the end. It needs Bash 4 or later.

Refresh the golden profile digests

scripts/test_profile_resolver.py checks that the Python copy of the compositor, scripts/profile_resolver.py, composes the same bytes as the browser. It pins one SHA-256 per persona (GOLDEN_PROFILES) over the profile the browser composes for --fingerprint=12345, and the list of sections that profile has (GOLDEN_SECTIONS). Take the digests from a native build. Digests recomputed with the resolver would make the test compare it with itself. Cores and memory are capped at the host’s, so use a host like GOLDEN_HOST, which is macOS on Apple silicon with 14 cores and 36 GiB. Every child process carries the composed profile in its --apostate-profile switch, so read it from ps while the browser runs. The loop picks the processes by their user data directory, so other Apostate browsers on the host do not interfere:

BIN=.workspace/src/out/macos-arm64/Chromium.app/Contents/MacOS/Chromium
for p in windows macos linux; do
  dir="$(mktemp -d)"
  "$BIN" --headless=new --fingerprint=12345 --fingerprint-platform=$p \
    --user-data-dir="$dir" about:blank >/dev/null 2>&1 & pid=$!
  sleep 5
  ps -Awwo args= | grep -F -- "$dir" | tr ' ' '\n' | grep -m1 '^--apostate-profile=' \
    | cut -d= -f2- | base64 -d > native-$p.json
  kill $pid; wait $pid 2>/dev/null
  python3 - native-$p.json <<'PY'
import hashlib, json, sys
profile = json.load(open(sys.argv[1]))
data = json.dumps(profile, sort_keys=True, separators=(",", ":"),
                  ensure_ascii=False).encode("utf-8")
print(sys.argv[1], sorted(profile))
print(hashlib.sha256(data).hexdigest())
PY
done

Run on an Apple M4 Max with 14 cores and 36 GiB against the 0.4.3 release browser, it prints the digests the test holds:

native-windows.json ['audio', 'battery', 'browser', 'cpu', 'extensions', 'fonts', 'gl_extensions', 'gl_limits', 'gl_precisions', 'gpu', 'id', 'media', 'memory', 'network', 'platform', 'screen', 'speech', 'theme', 'webgpu', 'window']
293bf5bd0750fe708ce7d1f8ed424bdcee28819ef008b35bbbc5a0c911e611bd
native-macos.json ['audio', 'battery', 'browser', 'cpu', 'extensions', 'fonts', 'gl_extensions', 'gl_limits', 'gl_precisions', 'gpu', 'id', 'media', 'memory', 'network', 'platform', 'screen', 'speech', 'theme', 'webgpu', 'window']
3738d7b64c6b52da997aac166ad6343f365821075562e66bfa860c56f4ff4b5e
native-linux.json ['audio', 'battery', 'browser', 'cpu', 'extensions', 'fonts', 'gl_extensions', 'gl_limits', 'gl_precisions', 'gpu', 'id', 'media', 'memory', 'network', 'platform', 'screen', 'speech', 'theme', 'webgpu', 'window']
9172c6dc5887087376e019f0ccb495301817d8723722c57f14213687d9b3c2bf

Paste each digest and section list into the test. A digest that differs while the sections match fails the test. When the sections differ from GOLDEN_SECTIONS, the test skips and names them. With APOSTATE_REQUIRE_NATIVE_GOLDENS=1 it fails instead, which is how the release gate runs it.

Archives and manifests

Each platform gets one archive named apostate-<chromium version>-<platform>, .tar.zst for Linux and .zip for macOS and Windows:

Platform	Archive	Size in v0.4.3
`linux-x64`	`apostate-152.0.7977.83-linux-x64.tar.zst`	192 MB
`linux-arm64`	`apostate-152.0.7977.83-linux-arm64.tar.zst`	195 MB
`macos-arm64`	`apostate-152.0.7977.83-macos-arm64.zip`	154 MB
`windows-x64`	`apostate-152.0.7977.83-windows-x64.zip`	185 MB

An archive holds the browser, the licence, build/MANIFEST.lock and the profile resources. Beside it is <archive>.manifest.json, with exactly the fields release/manifest.schema.json allows:

Field	Value
`package_version`	The release version from `.github/release/artifact-policy.json`
`chromium_version`	`152.0.7977.83`
`catalogue_version`	From `resources/profiles/catalogue.json` at the tagged commit
`platform`	The target
`artifact`	The archive name
`sha256`	SHA-256 of the whole archive
`source_revision`	The commit it was built from
`patch_series_sha256`	SHA-256 of `patches/series`
`build_manifest_sha256`	SHA-256 of the archive’s `build/MANIFEST.lock`

Do not replace a published archive with different bytes. Cut a new version.

Publish the packages

The packages download the browser and check it against a manifest they carry. To give them the new release’s digests:

gh release download v0.4.4 -D ./apostate-release
python3 scripts/sync-packages.py --release ./apostate-release --tag v0.4.4

sync-packages.py hashes every archive again, checks each manifest against the release policy, and writes release-manifest.json into python/apostate/assets/ and npm/assets/. It also copies the profile schema, the catalogue, the country-to-locale table and the font packs into both packages. Commit the changes, then build and publish both packages. The Python commands need the build and twine packages from PyPI.

python3 -m build --outdir dist python
twine upload dist/apostate-0.4.4*
npm publish ./npm

The MCP server

The MCP server, @heretic-tech/apostate-mcp in mcp/, has its own version in mcp/package.json, and sync-packages.py does not touch it. It depends on @heretic-tech/apostate ^0.4.3, so a new 0.4.x Node package reaches it without an MCP release. When mcp/ changes, or the Node package’s minor version changes, raise that range and the MCP version, run its test, and publish it. The first publish of a scoped package needs --access public:

cd mcp && npm ci && npx apostate install && npm test && cd ..
npm publish ./mcp --access public

The MCP server needs Node 22 or later. MCP server documents its options.

Verify a download

Each release archive has a GitHub build-provenance attestation from its build job, and both packages check an archive’s SHA-256 against its manifest before extracting it. Verify a download has the commands for checking an archive and a signed macOS bundle.

Reference

Contributing

Cut a release

What CI checks

Refresh the golden profile digests

Archives and manifests

Publish the packages

The MCP server

Verify a download

​Cut a release

​What CI checks

​Refresh the golden profile digests

​Archives and manifests

​Publish the packages

​The MCP server

​Verify a download

Cut a release

What CI checks

Refresh the golden profile digests

Archives and manifests

Publish the packages

The MCP server

Verify a download