Publishing Built-in Artifacts
Read BUILTIN_ARTIFACTS.md for the release contract and recovery procedure.
Source and build logic stay in golem; golemcloud/golem-builtins holds only
immutable release assets. Never commit generated WASMs or embed them in published
release binaries. Local install tasks opt into compressed embedding; source
overrides still take precedence. Release mode rejects the embedding feature.
Development and main CI build current sources with
cargo make ensure-builtin-artifacts. Do not publish development artifacts or
generate development tool versions. Exported tool versions differ from artifact
versions. Bump changed tools in source, registry provisioning, and defaults during
release preparation. Replacing local bytes does not rebind published tool
coordinates in an existing registry database.
Protected preparation
Use releasing-golem for the complete release order
and authorization gates. The normal publisher is the protected golem-release
job in prepare-golem-release.yaml, dispatched on the exact Golem tag. It runs
after full reusable CI preflight, creates or resumes the draft, publishes all eight
entries, and uploads the verified manifest. It never publishes the Golem draft.
All eight packages, including corresponding source, finish before the first
built-in upload. The upload pass reuses those packages without repackaging.
Only this job mints the GitHub App token from environment variable
RELEASE_APP_ID and secret RELEASE_APP_PRIVATE_KEY. The App needs contents
read/write on golemcloud/golem and golemcloud/golem-builtins. Restrict the
environment to release tags; required reviewers are recommended. Normal CI has
no built-in write token. The publisher's CI guard accepts only this workflow's
workflow_dispatch on the matching Golem tag in golemcloud/golem.
Authorized local recovery
Use Python 3.14 as python3 for source packaging; do not rely on the runner's
system Python. The protected publisher installs this version explicitly.
- Use a clean exact release-tag checkout with full history. Push the tag and
create a draft Golem GitHub release first. The tag must identify the exact
head of a PR merged into public
mainor the maintenance branch matching the tag version, not its squash commit. The merge commit must remain reachable from that public target branch. Use an authenticatedghsession with pull requests read access for source validation. - Run
BUILTIN_VERSION=<version> cargo make validate-builtin-releasefor source validation. AddBUILTIN_DRY_RUN=1tocargo make publish-builtin-artifactsto build and review packaging without writes to GitHub. Review exports, provenance, licenses, SBOM, hashes, and URLs. - Explicit invocation of
BUILTIN_VERSION=<version> cargo make publish-builtin-artifactsapproves publication of all eight inventory entries. Do not run it unless publication is requested. All use the tag version without its leadingv. - The task verifies public bytes, generates
builtin-artifacts.release.json, and uploads it to the Golem release without replacement. Wait for preparation to attach all native binaries before human draft publication with--latest=false(or uncheck Set as latest release in GitHub). Leave Latest promotion to the publication workflow. That event starts Docker publication without repeating full CI. Both native and Docker builds fetch the manifest and setGOLEM_BUILTIN_RELEASE=1before compilation. Do not commit the generated manifest.
The existing cargo make publish-builtin-artifact remains a manual packaging
entry point with BUILTIN_COMPONENT, BUILTIN_VERSION, BUILTIN_SKIP_BUILD=1,
and BUILTIN_DRY_RUN=1 for packaging inspection. Preserve provenance, licenses,
source archives, and applicable SPDX SBOMs. Never overwrite tags or assets.
On partial failure, rerun from the same source. The publisher verifies existing
assets, uploads only missing assets, and verifies the complete public set before
the outer task creates the manifest. A conflicting asset stops publication.
An existing manifest must be identical and is verified and reused. Never use
--clobber, move a tag, or bypass the CI guard. Changed bytes require a new tag.
Cross-host rebuilds need not produce identical WASM bytes. For explicitly authorized recovery that retains complete packages already verified by the original publisher and publishes only missing components, follow recovery across build hosts. Require the original verification evidence and verify every public asset before constructing the manifest. Do not bypass a byte mismatch in the all-entry task.