Publishing a release
Until 11 September 2026 this repository could build a release but not publish one. No build file
declared a publishing repository, so Gradle never created a PublishToMavenRepository task and
publishToMavenLocal was the only thing that worked; the generated POM was also missing the scm
block that Maven Central validation requires. This runbook describes the path that now exists.
What is wired up
| Piece | Where |
|---|---|
Publishing repository (central) |
build.gradle.kts, and distribution/bom/build.gradle.kts for the BOM |
POM completeness (scm, issueManagement, licences, developers) |
same two files |
| Mandatory signing on remote publication | build.gradle.kts, PublishToMavenRepository.doFirst |
CycloneDX SBOM attached as a cyclonedx classifier |
build.gradle.kts |
| Evidence gates, then publish | .github/workflows/release-evidence.yml |
| Static check that all of the above still exists | scripts/check-publication.py, run in CI |
scripts/check-publication.py also validates every generated POM under the build root and fails on
any missing required element, so a POM regression is caught before a tag is cut rather than by
Sonatype during staging.
One-time setup
These are the parts no script can do for you.
- Verify the
org.trustweavenamespace with Sonatype Central. This is a manual review with a DNS TXT record or a repository check, and it takes as long as it takes. - Create a signing key and record it as repository secrets:
TRUSTWEAVE_SIGNING_KEY— the ASCII-armoured private keyTRUSTWEAVE_SIGNING_PASSWORD— its passphrase- Optionally (recommended) set the repository variables
TRUSTWEAVE_SIGNING_PUBLIC_KEY(the ASCII-armoured PUBLIC key) andTRUSTWEAVE_SIGNING_FINGERPRINT(its full fingerprint). When the public key is set, the publish job imports it and runsgpg --verifyon every staged.ascbefore attesting; the fingerprint, when set, must also match the signing key. Without them the job still requires an.ascnext to every non-sidecar file but only warns that the signatures were not cryptographically checked.
- Record the portal credentials as
TRUSTWEAVE_PUBLISH_USERNAMEandTRUSTWEAVE_PUBLISH_PASSWORD. These are the portal’s generated token pair, not an account password. - Create a
maven-centralGitHub environment with at least one required reviewer. The publish job targets it, so a tag alone never publishes — a person approves each release. TRUSTWEAVE_PUBLISH_URLno longer affects tag releases: the workflow uploads to the Central Portal withscripts/upload-to-central.py. It still redirects Gradle’scentralrepository for manual rehearsals.
Release
- Update
versioninbuild.gradle.kts. The publish job refuses a tag whose name does not match the declared version, so these cannot drift apart. - Land the release commit on
mainand confirm CI is green. - Tag it:
git tag v0.7.1 && git push origin v0.7.1. release-evidence.ymlruns the evidence job: tests, lint, ABI, coverage policy, documentation execution, the VI cross-stack interoperability check against the pinned Python reference, reliability evidence, alert-rule validation, and provenance attestation. Before anything is built it also requires the tagged commit to be an ancestor oforigin/main, and it records the SHA-256 of every jar invalidation-manifest.json.- The
publishjob waits for a reviewer on themaven-centralenvironment. It then re-verifies the tag against the project version, regenerates and validates every POM, builds the signed artifacts once intobuild/release-staging, fails unless every staged jar is byte-identical to the jar the evidence job validated (the staged jar names must equal the evidence jar names minusconfig/release-unpublished-jars.json, the manifest must be from the tagged commit, and the minimum jar count derives from the manifest), requires an.ascfor every non-sidecar file, writesSHA256SUMS, attests it, re-verifies that attestation withgh attestation verifyjust before the upload, and only as its last step uploads that same directory to the Central Portal (scripts/upload-to-central.py, deployment typeUSER_MANAGED). A failure at any earlier step means nothing reached Central. The publish job also waits for theosv-gatejob, which runsscripts/check-osv-baseline.pyagainst a fresh scan at the tag. - Release the deployment in the Sonatype Central Portal.
- Publish the draft GitHub release the
release-assetsjob created for the tag, once the Portal shows the deployment as published. The job cannot check that itself (it would need a Central API call with the publish credentials, which only the upload step may see), so the release stays a draft until a person confirms it.
If verify-staged-jars.py reports a jar “validated by the evidence build but not staged”, that jar is built by
build but never published: add it to config/release-unpublished-jars.json with a reason. The list starts
empty; the first tag run shows whether any entry is needed.
What only a real tag run proves: the Portal accepts the bundle layout (including Gradle’s checksum
sidecars), the token-based Authorization: Bearer upload and that the answer is a deployment id, that the
rebuilt jars really are byte-identical in the CI environment, that the unpublished-jar allowlist is complete,
that Gradle signs every non-sidecar file (including the per-module CycloneDX SBOMs), that gh attestation verify
accepts the flags used, that the OSV scan job reproduces osv.json at the tag, and that the draft release flow
works with the installed gh. The script’s
verification, bundling and request construction are unit-tested; the HTTP exchange is not.
python scripts/upload-to-central.py --staging build/release-staging --name x --dry-run rehearses
everything except the network call.
Rehearsing without publishing
1
2
3
4
# Everything except the upload, against a throwaway local repository.
./gradlew publishToMavenLocal
./gradlew generatePomFileForMavenPublication
python scripts/check-publication.py
publishToMavenLocal does not require signing, so it stays usable for day-to-day development. Only
PublishToMavenRepository enforces TRUSTWEAVE_SIGNING_KEY and the publish credentials, and it
fails with a message naming the missing variable rather than uploading unsigned artifacts.
What is still not automated
- Namespace verification and the final “release” of the staged repository are manual portal steps.
- There is no automated rollback. A published version is immutable; a bad release is superseded by the next one.