Release process
August 2, 2026 ยท View on GitHub
Samsarix Core publishes approved GitHub releases from immutable version tags. PyPI publication is a separate owner decision and is not performed by this repository.
Safety boundary
The Release workflow accepts manual dispatches as build-only dry runs. It publishes
only for a pushed v* tag, requires that tag to match samsarix_core.__version__, and
requires the tag to point to the current default-branch head. The tag must already
exist; the workflow never creates or moves it. The publication procedure separately
requires repository release immutability to be enabled before the tag is pushed.
For a tag build, the workflow:
- builds the wheel and source distribution with
python -m build; - runs strict Twine metadata checks;
- installs the wheel without dependencies in a fresh environment and imports both the Samsarix API and compatibility namespace;
- creates a
SHA256SUMSmanifest; - generates GitHub Actions build-provenance attestations for both distributions; and
- creates a GitHub release containing the distributions and checksum manifest.
GitHub documents that attestations connect artifacts to their repository, commit, workflow, and build identity; they do not prove that the code is vulnerability-free. Published immutable releases prevent replacement of their associated tags and assets.
Prepare and dry-run
Before tagging:
- make the version in
pyproject.tomlandsrc/samsarix_core/_version.pyidentical; - close the matching changelog entry with a date;
- merge only after the complete CI matrix and package job pass; and
- run the build-only workflow from the exact
maincommit:
gh workflow run Release --ref main
gh run list --workflow Release --limit 1
gh run watch RUN_ID --exit-status
Enable release immutability in the repository settings before the first tag, then verify the setting through GitHub's repository API. This administrative check deliberately stays outside the narrowly scoped workflow token.
Publish
From a clean, current main checkout, create and push one annotated tag:
RELEASE_VERSION="<next-version>"
git tag -a "v${RELEASE_VERSION}" -m "Samsarix Core ${RELEASE_VERSION}"
git push origin "v${RELEASE_VERSION}"
The push is the publication authorization. Do not reuse or force-move a released tag. Alpha, beta, release-candidate, and development versions are marked as prereleases and are not selected as GitHub's latest stable release.
Verify
Download into a new directory and verify the release, exact assets, checksums, and build provenance:
RELEASE_VERSION="<published-version>"
gh release verify "v${RELEASE_VERSION}" --repo Deathcharge/samsarix-core
gh release download "v${RELEASE_VERSION}" --repo Deathcharge/samsarix-core
gh release verify-asset "v${RELEASE_VERSION}" "samsarix_core-${RELEASE_VERSION}-py3-none-any.whl" \
--repo Deathcharge/samsarix-core
sha256sum --check SHA256SUMS
gh attestation verify "samsarix_core-${RELEASE_VERSION}-py3-none-any.whl" \
--repo Deathcharge/samsarix-core
gh attestation verify "samsarix_core-${RELEASE_VERSION}.tar.gz" \
--repo Deathcharge/samsarix-core
Then install the verified wheel in a fresh supported Python environment and run the documented example before recording the release as complete.
Recovery
An immutable release is intentionally not edited in place. If a published artifact or contract is wrong, document the issue, prepare a new version, rerun the complete gate, and publish a new tag. Consumers can roll back by installing a previously verified release asset or exact commit. Core stores no remote runtime state.
Published evidence: v2.0.0a5
The lifecycle-observability alpha was published on 2026-08-02 as an immutable GitHub prerelease:
| Evidence | Value |
|---|---|
| Release | v2.0.0a5 |
| Tagged commit | 60fa5554d8ef4625dc803751cc4bd34cf757e094 |
| Annotated tag object | a5b64aac040f87e0746e987e7c773a65a6557f26 |
| Release workflow | run 30746440097 |
| Build-only dry run | run 30746407482 |
| Exact-main CI | run 30746378277 |
| Release state | published, prerelease, immutable |
Published assets are:
| Artifact | Bytes | SHA-256 |
|---|---|---|
samsarix_core-2.0.0a5-py3-none-any.whl | 46,592 | a883741055ef00a38ca01a93a41e761a419d7070210e3f94fe8cc69da8e6ab27 |
samsarix_core-2.0.0a5.tar.gz | 115,681 | b7d86c52a30924b5dc158d576589134054ffb334944ca3ed832735c45383c893 |
SHA256SUMS | 200 | ee8decc978e7894c68e65d1ae7fdef932c79c41c56d25914e68f9c1403cbf139 |
gh release verify confirmed the immutable release, and gh release verify-asset
confirmed all three freshly downloaded assets. The downloaded manifest independently
matched both distribution digests. gh attestation verify validated SLSA provenance
for the wheel and source distribution while explicitly requiring the public release
workflow, tag ref, source commit, and GitHub-hosted runner.
A fresh Python 3.14.6 environment installed the downloaded wheel without dependencies
and reported no broken requirements. An installed-package probe invoked a real tool and
received correlated started and success lifecycle events without retaining the
private argument in their serialized metadata. Both public namespaces reported
2.0.0a5, and the import resolved to the fresh environment's site-packages. This is
GitHub distribution, provenance, and clean-wheel behavior evidence, not PyPI
publication, a stable-API declaration, a security audit, third-party production
adoption, or an SLA.
Published evidence: v2.0.0a4
The per-tool bulkhead alpha was published on 2026-08-02 as an immutable GitHub prerelease:
| Evidence | Value |
|---|---|
| Release | v2.0.0a4 |
| Tagged commit | 27c871942b0e90d8303d212b438d5251cb28d43f |
| Annotated tag object | ff2ce612186ed60f27f5de027c67db7d8a1d335e |
| Release workflow | run 30744216376 |
| Build-only dry run | run 30744149615 |
| Exact-main CI | run 30744070502 |
| Release state | published, prerelease, immutable |
Published assets are:
| Artifact | Bytes | SHA-256 |
|---|---|---|
samsarix_core-2.0.0a4-py3-none-any.whl | 45,262 | 25c91cb597728db18c822da9494de5c64e4747d86519ee5d8eedae01b2570e0d |
samsarix_core-2.0.0a4.tar.gz | 107,730 | b215462cc741f7c7da4d487e6e00768ca4cb44862c20e78f7708121a5e4aa40f |
SHA256SUMS | 200 | 45c818e9be236d845b4c909d2b843bd56bf03ab189429f83c4d20f053de3e83e |
gh release verify confirmed the immutable release, and gh release verify-asset
confirmed all three downloaded assets. The downloaded manifest independently matched
the wheel and source-distribution digests. gh attestation verify validated one SLSA
provenance statement covering both distributions. Its certificate and predicate bind
the public repository, .github/workflows/release.yml, tag v2.0.0a4, GitHub-hosted
run 30744216376, and source commit 27c871942b0e90d8303d212b438d5251cb28d43f;
the signature has a public Sigstore transparency-log timestamp.
A fresh Python 3.11.9 environment installed the downloaded wheel without dependencies
and reported no broken requirements. An installed-package behavioral probe registered
one tool with max_concurrency=1, queued a second call to it, and completed an unrelated
tool through the remaining global slot. All three calls succeeded in input order, both
public namespaces reported 2.0.0a4, and final pending/in-flight metrics were zero.
This is GitHub distribution and provenance evidence, not PyPI publication, a stable-API
declaration, a security audit, third-party production adoption, or an SLA. The independent
consumer now pins the post-release lifecycle commit while its installed metadata remains
2.0.0a4; consumers can roll back to this verified release.
Published evidence: v2.0.0a3
The runtime-admission alpha was published on 2026-08-02 as an immutable GitHub prerelease:
| Evidence | Value |
|---|---|
| Release | v2.0.0a3 |
| Tagged commit | 8e3d9460709a21b84934bc64e975824ca1882046 |
| Release workflow | run 30741229489 |
| Build-only dry run | run 30741086085 |
| Release state | published, prerelease, immutable |
Published assets are:
| Artifact | Bytes | SHA-256 |
|---|---|---|
samsarix_core-2.0.0a3-py3-none-any.whl | 44,424 | dc32cf61d806668ad8528ca7b19beabbd125a1f98de56f527052433e2cb43c34 |
samsarix_core-2.0.0a3.tar.gz | 102,420 | 198ab9be86659a45d9ba8007aa4a1ab68408e9d89e583b52a070db8422c01432 |
SHA256SUMS | 200 | e82f75c0c5a6f9fca7d34fc2fe3ccde70ca23c32201f11dd199ec32866e59e17 |
gh release verify confirmed the immutable release attestation, while
gh release verify-asset confirmed every downloaded asset. gh attestation verify
validated SLSA provenance covering the wheel and source distribution. The verified
identity names Deathcharge/samsarix-core/.github/workflows/release.yml, tag
v2.0.0a3, GitHub-hosted run 30741229489, and source commit
8e3d9460709a21b84934bc64e975824ca1882046; the signature has a public Sigstore
transparency-log timestamp. The tag and local main resolved to the same commit.
A fresh Python 3.11.9 environment installed the downloaded wheel without dependencies,
reported no broken requirements, and confirmed the public and legacy namespaces report
2.0.0a3 plus the busy status. This is a GitHub distribution and provenance record,
not a PyPI publication, stable-API declaration, security audit, production-adoption
claim, or service-level commitment.
The preceding immutable v2.0.0a2 tag failed closed during wheel smoke testing because
the release workflow contained a stale legacy-namespace version literal. Run
30740957122
stopped before tag/version validation, attestation, or publication, and no GitHub release
exists for that tag. The smoke test now compares both namespaces dynamically; its
build-only run passed before v2.0.0a3 was created. The failed tag was not moved or
deleted.
Published evidence: v2.0.0a1
The first Samsarix-branded alpha was published on 2026-08-02 as an immutable GitHub prerelease:
| Evidence | Value |
|---|---|
| Release | v2.0.0a1 |
| Tagged commit | 5f09432ebdb3d2b113b8fdb53112e39680ca5c25 |
| Release workflow | run 30739840774 |
| Build-only dry run | run 30739778395 |
| Release state | published, prerelease, immutable |
Published assets are:
| Artifact | Bytes | SHA-256 |
|---|---|---|
samsarix_core-2.0.0a1-py3-none-any.whl | 43,818 | 8bc4b7b438bff0ab0a1586dc3300959c3410eaa6be50b3ddb674e61177b3b0e1 |
samsarix_core-2.0.0a1.tar.gz | 99,218 | fadca316836530743e411859678610c71b1cbf0c3709074ba8330d7bcc7edec7 |
SHA256SUMS | 200 | 7cc9dd0ef0bb0a5fc33a9abd3378d84b8593516989f1789cbe316ffe39358d57 |
gh release verify confirmed GitHub's immutable release attestation, and
gh release verify-asset confirmed all three downloaded assets. gh attestation verify
validated a SLSA provenance statement covering the wheel and source distribution. Its
verified identity names Deathcharge/samsarix-core/.github/workflows/release.yml, tag
v2.0.0a1, GitHub-hosted run 30739840774, and source commit
5f09432ebdb3d2b113b8fdb53112e39680ca5c25; the signature has a public Sigstore
transparency-log timestamp.
A fresh Python 3.11.9 environment installed the downloaded wheel without dependencies,
reported no broken requirements, and completed examples/policy_gate.py: the unscoped
call was denied with the safe tool_denied result and the scoped call succeeded. This
is a GitHub distribution and provenance record, not a PyPI publication, stable-API
declaration, security audit, production-adoption claim, or service-level commitment.
Primary references: