Releasing
How a release is cut: the manual workflow, what one run builds for six targets and ten languages, trusted publishing and the setup each registry needs, dry runs, and where each registry page gets its text.
Releases are cut by hand from the Release workflow
(.github/workflows/release.yml), never by pushing a tag. One run builds
every artefact for one version from one commit, publishes the GitHub
Release and publishes each package to its registry. A dry run does
everything except create the tag, the release and the registry uploads,
so the pipeline can be exercised without touching a registry.
This procedure describes the 0.3.1 source tree: vault schema 5, C ABI 2, contract 2, and one package version across the CLI and SDKs. The version remains unreleased until the changelog has a dated 0.3.1 heading and the release workflow publishes it. Pushing a branch does not publish packages.
Procedure
Section titled “Procedure”- Choose the version by ADR 0007:
before 1.0 a patch may add but never breaks any surface (CLI, Rust
API, C ABI, contract, SDKs, vault file); anything else is a minor
release. A C ABI change needs
SO_ABI_VERSIONbumped, a contract changeCONTRACT_VERSION. Thesemverjob of the workflow checks the Rust API against crates.io for the version you type and fails the run when a bigger bump is needed. UpdateCHANGELOG.md: move the[Unreleased]entries under a new## [X.Y.Z] - YYYY-MM-DDheading. With the repository at that version (python scripts/release/set-version.py X.Y.Z --keep-node-links), runpython scripts/release/docs-version.py: every install page then names X.Y.Z and no longer says it is unreleased. The workflow refuses a real release whose documentation does not (docs-version.py --check --expect X.Y.Z). Commit tomain, then push the complete release candidate once. A Git push makes that commit available to Actions; it does not start a release. - In GitHub, open Actions → Release → Run workflow, enter the version
(
X.Y.Z, nov) and leave dry_run ticked. Tick bootstrap_providers only when a crate is published for the first time (below); every current crate is on crates.io, so 0.3.1 leaves it off. Wait for green. Therelease-dry-run-X.Y.Zartifact holds everything the real run would attach, plusSHA256SUMSand the release notes; download it and try a package or two. - Manually dispatch the workflow again from the same reviewed commit,
with the same version and provider option, and dry_run unticked.
It creates the tag
vX.Y.Zon the chosen commit, the GitHub Release with every archive and package andSHA256SUMS, then the publish jobs run (or are skipped, see below). - Check the registries. When work on the next version starts, bump the
repository to it (
set-version.py X.Y.Z --keep-node-links) and rundocs-version.py: the install pages name the new version and say it is not released yet, with a link to building that source version. CI checks the pages against the workspace version on every change (docs-version.py --check).
The workflow refuses a version that is not semver and, outside a dry run,
a tag that already exists. It also refuses a real release that is not
dispatched from main, or whose commit was not validated in full:
scripts/release/check-release-validation.py requires the commit to be on
main, a completed ci.yml run for exactly that commit (a push or a
dispatch on main, in this repository) in which every job ran and passed,
and the commit’s CI check reported by GitHub Actions. A commit whose
push was docs-only skipped the build jobs: run CI on it with Actions → CI
→ Run workflow on main first. Any failure to read the GitHub API
refuses. A dry run runs the same gate and reports its verdict as warnings,
so release changes can be tried from a branch. Release packages applies
the same gate to the commit the tag names. Published package contents are
immutable; code changes require a new version. A failed registry upload can instead be
retried for the same version with Release packages.
What one run produces
Section titled “What one run produces”| Job | Output |
|---|---|
sbom |
sourceorrery-X.Y.Z-<target>.cdx.json, sourceorrery-ffi-X.Y.Z-<target>.cdx.json, sourceorrery-python-X.Y.Z-<target>.cdx.json, sourceorrery-node-X.Y.Z-<target>.cdx.json: CycloneDX 1.5 bills of materials for the six targets, rendered from the lock files by cargo cyclonedx on one runner (artifact sbom). The native job builds the CLI and the C ABI with cargo auditable, which embeds the dependency list in the binaries. |
semver |
nothing: cargo semver-checks on sourceorrery and sourceorrery-core against the crates.io baseline, with the version you typed; the release waits for it. |
native (six targets) |
sourceorrery-X.Y.Z-<target>.{tar.gz,zip}: the CLI. sourceorrery-ffi-X.Y.Z-<target>.{tar.gz,zip}: the shared and static C ABI libraries, sourceorrery.h, sourceorrery.hpp, licences. On Windows the C runtime is linked statically (.cargo/config.toml), and scripts/release/check-pe-imports.py fails the job if sourceorrery.exe or sourceorrery_ffi.dll imports a C runtime DLL: they must run without the Visual C++ Redistributable, as WinGet’s validation runs them. |
python (six targets + sdist) |
abi3 wheels for Python 3.11+ (manylinux_2_28 on Linux) and the sdist. |
node-build, node-package |
@sourceorreryai/sdk and the six @sourceorreryai/sdk-<platform> tarballs. node-build compiles the addon per target and, on x86_64-unknown-linux-gnu, keeps the index.js loader and index.d.ts that napi build generates (artifact npm-loader); node-package lays out the platform packages around the addons, adds the loader, packs, then installs the main and linux-x64-gnu tarballs into a scratch project and requires @sourceorreryai/sdk, so a main package that cannot be loaded fails the run. |
java |
sourceorrery-X.Y.Z.jar with the native libraries embedded per platform. |
dotnet |
SourceOrrery.X.Y.Z.nupkg with runtimes/<rid>/native. |
crates |
scripts/release/publish-crates.py X.Y.Z runs Cargo’s dry-run verification for every publishable workspace crate in dependency order. |
publish-crates |
in a real release, publishes the workspace crates through OIDC. With bootstrap_providers, the crates in the helper’s bootstrap list that crates.io does not have yet go first, with the scoped CRATES_BOOTSTRAP_TOKEN. Exact versions already published are skipped. All ordinary release and SDK jobs still run. |
php |
composer validate --strict on the root composer.json and a Composer install of the version from a local tag (scripts/ci/php-package-install.sh); nothing is uploaded, the package Packagist serves is the git tag itself. |
release |
the GitHub Release (or the dry-run artifact) with SHA256SUMS, and a build provenance attestation for every file in a real release. |
package-managers |
the Homebrew formula, the Scoop manifest and the three WinGet manifests, rendered from SHA256SUMS by scripts/release/package-managers.py (artifact package-managers); every URL is a release archive and every hash comes from the release. |
Targets: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu,
x86_64-apple-darwin, aarch64-apple-darwin, x86_64-pc-windows-msvc,
aarch64-pc-windows-msvc.
Every manifest is stamped with the version first by
scripts/release/set-version.py (Cargo manifests and lock files, the
Python package, package.json and the npm/<platform> manifests,
pom.xml, Directory.Build.props); Go and PHP take their version from
the tag. In the repository bindings/node/package.json depends on the
platform packages as file:npm/<platform> links so that npm ci resolves
without them being on the registry; stamping replaces the links with the
version, which is what the published package depends on, so the node jobs
run npm ci before they stamp.
Registry credentials
Section titled “Registry credentials”No publish job runs in a dry run. crates.io, PyPI, npm and NuGet are
published by trusted publishing: the job presents the identity token
GitHub signs for that workflow run, and the registry exchanges it for a
short-lived credential, granted only if the package’s trusted-publisher
settings name Netizine/sourceorrery and the workflow file. No token for
them is stored for normal releases. All current crates, including the
Azure provider and OS helper, use trusted publishers. Maven
Central and Packagist still use stored
secrets (Settings → Secrets and variables → Actions); their jobs are
skipped, not failed, while the secrets are absent. The Release
packages workflow (below) needs the
same settings, with its own file name, ReleasePackages.yaml.
| Registry | Release job | Runs when | Stored credential |
|---|---|---|---|
| crates.io | publish-crates |
every real release | none for normal releases |
| PyPI | publish-pypi |
every real release | none (trusted publishing) |
| npm | publish-npm |
the repository variable NPM_TRUSTED_PUBLISHING is true |
none (trusted publishing) |
| NuGet | publish-nuget |
the secret NUGET_USER exists |
none besides the profile name (trusted publishing) |
| Maven Central | publish-maven |
its secrets exist | MAVEN_CENTRAL_USERNAME, MAVEN_CENTRAL_PASSWORD, MAVEN_GPG_PRIVATE_KEY, MAVEN_GPG_PASSPHRASE |
| Packagist | publish-packagist |
its secrets exist | PACKAGIST_USERNAME, PACKAGIST_API_TOKEN |
| pkg.go.dev | publish-go |
every real release | none (uses GITHUB_TOKEN) |
| Homebrew tap, Scoop bucket | publish-homebrew-scoop |
the secret PACKAGING_TOKEN exists |
PACKAGING_TOKEN |
| WinGet | publish-winget |
the secret WINGET_TOKEN exists |
WINGET_TOKEN |
crates.io and PyPI have no switch: a registry that does not trust the
workflow fails the job loudly instead of skipping it. No secret is needed
for the GitHub Release itself (GITHUB_TOKEN with contents: write).
Setting up each registry
Section titled “Setting up each registry”npm (@sourceorreryai/sdk and six @sourceorreryai/sdk-<platform>
packages), with trusted publishing, so no token is stored anywhere. The
publish jobs run npm 11 (trusted publishing needs 11.5.1 or later), which
trades the job’s GitHub identity token for a short-lived credential; npm
grants it only to the workflows each package lists. npm can only attach a
trusted publisher to a package that exists, so the first version of each
package is published by hand, once.
- The npmjs.com account
sourceorreryai, with two-factor authentication. The packages live in its user scope,@sourceorreryai. - The first version, by hand: download the release’s seven npm tarballs
(
sourceorreryai-sdk-*.tgz), runnpm login, thennpm publish ./<tarball> --access publicfor the six platform tarballs and, last, the main one, confirming each with two-factor authentication. Keep the./: npm reads a path such asdist/<tarball>as a GitHub repository. - For each of the seven packages, at
https://www.npmjs.com/package/<name>/access, Trusted Publisher → GitHub Actions: Organization or userNetizine, Repositorysourceorrery, Workflow filenamerelease.yml, Environment empty (releaseonce the release environment is set up); then a second one withReleasePackages.yaml. Every field is case-sensitive, and npm checks them only when a publish happens. npm’s documentation says a new trusted publisher expires if no publish uses it within two days, so add them shortly before the release that will use them. - The repository variable (not secret)
NPM_TRUSTED_PUBLISHINGset totrue(Settings → Secrets and variables → Actions → Variables). Without it both workflows skip npm. - Optionally, once a release has gone through: each package’s Settings → Publishing access → Require two-factor authentication and disallow tokens. Trusted publishing keeps working; no token can publish.
PyPI (sourceorrery), with trusted publishing, so no token is stored
anywhere. pypa/gh-action-pypi-publish trades the job’s GitHub identity
token for a short-lived upload token and uploads a signed attestation
(PEP 740) with every file.
- A pypi.org account (two-factor authentication is mandatory) that owns
the
sourceorreryproject. - The project’s Manage → Publishing → Add a new publisher → GitHub:
Owner
Netizine, Repository namesourceorrery, Workflow namerelease.yml, Environment name empty (releaseonce the release environment is set up). Then a second publisher with Workflow nameReleasePackages.yaml. - Delete any
PYPI_API_TOKENrepository secret and revoke the token on pypi.org; nothing reads it any more.
crates.io (sourceorrery-core, sourceorrery-crypto,
sourceorrery-storage, sourceorrery-os, sourceorrery-provider-vault,
sourceorrery-provider-aws, sourceorrery-provider-azure,
sourceorrery-provider, sourceorrery, sourceorrery-ffi,
sourceorrery-cli), with trusted publishing for normal
releases. scripts/release/publish-crates.py discovers the publishable
workspace members, verifies their versions and lets Cargo publish them in
dependency order. Both release workflows skip exact versions already on
crates.io, including versions uploaded during bootstrap. A registry lookup
error or a yanked version fails the job; it is never treated as permission
to publish. rust-lang/crates-io-auth-action trades the
job’s GitHub identity token for a crates.io token that lives 30 minutes
and revokes it when the job ends. crates.io grants it only for crates
whose settings name the workflow, so every crate needs the setting, or the
publish stops at the first crate without it. A crate that crates.io does
not have yet has no settings: its first publication runs with
bootstrap_providers (with CRATES_BOOTSTRAP_TOKEN), and the steps
below follow it for that crate. Every current crate is on crates.io
with its setting, so a release leaves bootstrap_providers off.
- For each crate, Settings → Trusted Publishing → Add →
GitHub: Repository owner
Netizine, Repository namesourceorrery, Workflow filenamerelease.yml, Environment empty (releaseonce the release environment is set up). Then a second configuration withReleasePackages.yaml. - Delete any
CARGO_REGISTRY_TOKENrepository secret and revoke the token under Account Settings → API Tokens. - Optionally, once a release has gone through: each crate’s Settings → Trusted Publishing → Only allow trusted publishing, so that no API token can publish it.
Packaging checks and future first publications
Section titled “Packaging checks and future first publications”For local packaging validation without uploads:
python3 scripts/release/publish-crates.py 0.3.1The helper defaults to dry-run; only --publish permits uploads. Registry
lookups and Cargo packaging still need network access. Existing versions
are skipped and yanked versions or registry lookup errors stop the run.
The workflow’s bootstrap_providers option is for a crate’s first
publication. Before using it, review the helper’s bootstrap allowlist and the temporary
token scope, then configure that new crate’s trusted publisher and revoke
the token. Do not use bootstrap as the normal release path.
NuGet (SourceOrrery), with trusted publishing, so no API key is
stored anywhere. The publish jobs trade the job’s GitHub identity token
for a NuGet key that lives one hour, through NuGet/login; nuget.org
grants it only to the workflows its policy names.
- Sign in to nuget.org, click your user name, then Trusted Publishing.
- Add a policy, owned by your account (or the organisation that will own
the package): Repository Owner
Netizine, Repositorysourceorrery, Workflow Filerelease.yml(the file name only), Environment empty (releaseonce the release environment is set up). Allow publishing new packages and new versions, globSourceOrrery. The policy works before the package exists; the first push creates it. - Add a second, identical policy with Workflow File
ReleasePackages.yaml, so the Release packages workflow can push too. - Save your nuget.org profile name (the user name, not the e-mail
address) as the repository secret
NUGET_USER.
A new policy can show as temporarily active for 7 days, mostly for private repositories, until a first publish locks it to the repository; if nothing publishes in that window it turns inactive and can be restarted from the same page.
Maven Central (ai.sourceorrery:sourceorrery):
-
An account at central.sonatype.com.
-
Namespaces → Add namespace
ai.sourceorrery. Central shows a verification key; add it as a DNS TXT record onsourceorrery.ai, then press Verify. -
Account → Generate User Token. Its username is
MAVEN_CENTRAL_USERNAME, its passwordMAVEN_CENTRAL_PASSWORD(not the account’s login). -
A signing key, published where Central looks for it:
Terminal window gpg --full-generate-key # RSA 4096, with a passphrasegpg --keyserver keys.openpgp.org --send-keys <KEY-ID> # then confirm the e-mail it sendsgpg --keyserver keyserver.ubuntu.com --send-keys <KEY-ID>gpg --armor --export-secret-keys <KEY-ID> # the whole block is MAVEN_GPG_PRIVATE_KEYThe passphrase is
MAVEN_GPG_PASSPHRASE.
Packagist (sourceorrery/sourceorrery): the one-time submission
under The PHP package and Packagist,
then the account name as PACKAGIST_USERNAME and its safe API token
(Profile → Show API Token) as PACKAGIST_API_TOKEN. The release job
asks Packagist to re-read the repository, fails with that pointer if the
repository was never submitted, and waits for the version to appear.
pkg.go.dev: nothing to set up. The release job pushes the tag
bindings/go/vX.Y.Z and fetches the version through proxy.golang.org,
which indexes it.
Homebrew tap and Scoop bucket (Netizine/homebrew-sourceorrery,
Netizine/scoop-sourceorrery): the release job commits
Formula/sourceorrery.rb to the tap and bucket/sourceorrery.json to the
bucket, both rendered from the release’s SHA256SUMS. Users run
brew install Netizine/sourceorrery/sourceorrery and
scoop bucket add sourceorrery https://github.com/Netizine/scoop-sourceorrery
then scoop install sourceorrery. The manifest also carries checkver and
autoupdate, so a bucket that runs Scoop’s Excavator would follow releases
by itself; the job keeps it current either way.
- The two repositories, each with a licence and nothing else needed.
- A fine-grained personal access token (Settings → Developer settings →
Fine-grained tokens) limited to those two repositories with
Contents: read and write, saved as the repository secret
PACKAGING_TOKEN. Set an expiry and note it. An absent secret skips the job; an expired token or missing repository permissions fails it. If GitHub returns403, check access to both repositories and the token’s Contents: read and write permission before retrying.
WinGet (Netizine.SourceOrrery): the release job renders the three
manifests (version, installer, defaultLocale, manifest schema 1.12,
installer type zip with a portable nested installer) and runs
wingetcreate submit, which forks microsoft/winget-pkgs under the
token’s account and opens a pull request there. The first submission of a
package and every version after it go through that repository’s automated
validation and, for a new package, a moderator; a version is installable
once its pull request is merged, usually within a few days.
- A classic personal access token with the
public_reposcope (a fine-grained token cannot open a pull request on a repository you do not own), saved as the repository secretWINGET_TOKEN. wingetcreatecreates the fork on first use. For the first contribution, the account holder must also review and accept Microsoft’s Contributor License Agreement when its policy bot requests it on the pull request. Check the actual submission status before advertising WinGet availability; a release upload alone does not put a package in its catalog.
Repository and registry controls
Section titled “Repository and registry controls”The committed workflows require a real release to come from main and
from an exact commit whose full CI run passed. Package recovery verifies
release provenance and checks that the tag still names the validated
commit. These checks are in source; they do not configure GitHub or
registry account settings.
Before publication, inspect the external controls separately:
- Protect
mainwith the requiredCIcheck, strict status checks, appropriate reviews and administrator coverage. - Protect
v*andbindings/go/v*tags against update/deletion and limit tag creation to the release workflow. - Configure the
releaseenvironment (below): limited tomain, holding the registry credentials, optionally with required review. - Bind trusted publishers to the intended repository, workflow and environment. A GitHub secret’s presence does not prove registry trust.
- Check release immutability, default workflow-token permissions and restrictions on untrusted pull requests.
Historical repository observations are retained in the remediation validation ledger (opens in a new tab). They are dated evidence, not proof that an external setting still has the same value. Recheck these settings before a release.
The release environment
Section titled “The release environment”The jobs that can publish run in the GitHub environment release: in
release.yml every publish-* job and preflight, which reads the
registry secrets; in Release packages plan and every job that holds
a secret or an identity token. A dry run puts its jobs in
release-dry-run instead. GitHub creates an environment, with no rules,
the first time a job names it, and repository secrets reach every
environment, so the workflows publish as before until the environment is
configured. Then, in this order:
- Settings → Environments →
release: under Deployment branches and tags choose Selected branches and tags and addmain. Optionally add yourself as a required reviewer: each job in the environment then waits for an approval (preflightwhen a release starts, the publish jobs once the GitHub Release exists). - Move the registry secrets into the environment’s secrets and delete the
repository copies:
NUGET_USER,MAVEN_CENTRAL_USERNAME,MAVEN_CENTRAL_PASSWORD,MAVEN_GPG_PRIVATE_KEY,MAVEN_GPG_PASSPHRASE,PACKAGIST_USERNAME,PACKAGIST_API_TOKEN,PACKAGING_TOKEN,WINGET_TOKENandCRATES_BOOTSTRAP_TOKEN. Leaverelease-dry-runwithout secrets; a dry run then skips the Homebrew, Scoop and WinGet jobs, which need their token to run at all. - Set Environment
releaseon every trusted publisher, for both workflow files: each crate on crates.io, PyPI, each npm package, and NuGet’s two policies. An identity token from a dry run, a branch or any job outside the environment is then refused.
The next real release exercises it: a registry that does not accept the environment fails its job (crates.io and PyPI loudly), and Release packages can publish that registry once its setting is fixed.
Publishing an existing release
Section titled “Publishing an existing release”.github/workflows/ReleasePackages.yaml (Actions → Release packages →
Run workflow) publishes the packages of a release that already exists,
for a registry that was set up after the release ran or failed during it.
It builds no new release:
- npm, PyPI and NuGet upload the exact files attached to the release.
- crates.io publishes from the release tag’s source.
- Maven Central rebuilds the jar from the tag with the native libraries out of the release’s jar, because Central needs sources, javadoc and signatures, which the release does not carry.
- Packagist and pkg.go.dev upload nothing; they are pointed at the tag.
- The Homebrew tap, the Scoop bucket and WinGet get manifests rendered from
the release’s
SHA256SUMSwith the renderer in the checkout, so a fix to the renderer can be applied to an existing release.
Before anything is uploaded, every file is verified against the release
run’s own provenance (scripts/release/verify-release-artifacts.py): the
release’s SHA256SUMS must carry a build provenance attestation from
release.yml of this repository, on a GitHub-hosted runner, for the commit
the release gate validated (the tag’s), and only then is it the
inventory; the downloaded files must be exactly its files for that
registry (none missing, none extra), each with its digest and its own
attestation. The jobs that build from the tag (crates.io, Maven Central)
or tag it (pkg.go.dev) check the tag still names that commit, since tags
are not protected (above). A release without provenance, built before
attestations, is refused: publish a new version instead, or have its files
reviewed separately; there is no switch that skips the check. A dry run
verifies the same way.
Inputs: the tag (empty means the latest release), dry_run (on by
default), one tick box per registry, and bootstrap_providers for the
initial publication of the new crates in the helper’s bootstrap inventory. Every registry’s files are
checked before anything is uploaded, a version a registry already has is
skipped, and npm, NuGet, Maven Central and Packagist are skipped while
their variable or secrets are missing; a ticked crates.io or PyPI box
publishes using its configured trust (with the temporary provider-token
exception above). A dry run checks every ticked
registry, with or without secrets, and uploads nothing. It reports a
release-gate problem as a warning, except one: a tag whose commit is not on
main is refused, because the crates.io and Maven Central jobs build that
commit’s code while they hold id-token: write, so a dry run runs only
code already merged. It never imports the Maven signing key (the dry run
builds unsigned).
For a partially completed 0.3.1 release, select v0.3.1 and the failed
registries, run a dry run, then dispatch again with dry_run unticked.
Tick bootstrap_providers only while a crate in the helper’s bootstrap
list is still missing from crates.io. The job uses the release tag’s sources and skips
existing exact versions, so a failed upload does not require a new version. Changed package contents do.
What each registry page shows
Section titled “What each registry page shows”Each package’s page is written for someone who has just found it there: what the package is, that vaults are created and secrets stored with the CLI (no SDK installs it), and where the documentation is. Change the text in its source:
| Page | Text comes from |
|---|---|
| crates.io, each crate | crates/<crate>/README.md (the readme key in its Cargo.toml), plus description, keywords and categories |
| PyPI | bindings/python/README.md and description in bindings/python/pyproject.toml |
npm, @sourceorreryai/sdk |
bindings/node/README.md and description in bindings/node/package.json |
| npm, the six platform packages | scripts/release/npm-platform-packages.py, which the release runs after napi create-npm-dirs regenerates bindings/node/npm/<platform>/ |
| NuGet | bindings/dotnet/README.md (PackageReadmeFile) and Description in SourceOrrery.csproj |
| Maven Central | name, description and url in bindings/java/pom.xml; the javadoc’s package overview is package-info.java |
| pkg.go.dev | bindings/go/README.md and the package comment in sourceorrery.go |
| Packagist | the repository’s root README.md (Packagist reads a GitHub repository’s README, whatever composer.json says) and description in composer.json |
| GitHub Release | the Release notes step of release.yml; the CLI archives carry crates/sourceorrery-cli/README.md, the C ABI archives scripts/release/ffi-archive-README.md |
Registries take the text from the version they publish, so a change shows up with the next release; Packagist alone re-reads the root README whenever it updates the package.
The PHP package and Packagist
Section titled “The PHP package and Packagist”Packagist and Composer vcs repositories read one file, composer.json
at the root of the repository, and turn every git tag that carries one
into a version; neither can be pointed at a subdirectory. Three ways to
publish a package whose code lives in bindings/php were weighed:
- The repository is the package.
composer.jsonat the root autoloadsSourceOrrery\frombindings/php/src/. The release tag is the Packagist version, andcomposer requiredownloads GitHub’s archive of the tag (the whole tree, about 1.5 MB) intovendor/sourceorrery/sourceorrery. Nothing else moves. - A subtree split. The release job would push the history of
bindings/phpto a second repository (Netizine/sourceorrery-php), tag it there, and Packagist would follow that repository. A leaner download, at the price of a second repository, a token that can push to it, and a split that has to be re-run for every release and can drift from the tag. - Monorepo support on Packagist. Only Private Packagist can index a subdirectory; packagist.org cannot.
The first option is the lightest and the only one whose versions are the release tags themselves, so it is what the repository does. Consequences:
bindings/php/composer.jsonis gone; the root manifest is the only one. It mapsSourceOrreryException.phpandProject.phpin a classmap next to the PSR-4 rule because each holds more than one class, which PSR-4 alone cannot find.- The whole tree ships.
archive.excludeincomposer.jsonwould not trim it (it only shapescomposer archive, which Packagist never runs), and.gitattributes export-ignorewould also strip the Source code archives GitHub attaches to every release, so neither is used. scripts/ci/php-package-install.shcopies the checkout into a scratch repository, tags it, and provescomposer requireof that version and Composer’s autoloading of every class. Thesdk-phpCI job runs it on every push and thephprelease job runs it with the release version.
What the Packagist submission needs, once and by hand:
- This change on
main: Packagist reads the default branch when a repository is submitted and refuses one without a rootcomposer.json. - A packagist.org account (its name is
PACKAGIST_USERNAME) that submitshttps://github.com/Netizine/sourceorreryat https://packagist.org/packages/submit (opens in a new tab). The package name comes from the manifest,sourceorrery/sourceorrery; the first submission claims thesourceorreryvendor for that account. - The account’s API token (Profile → Show API Token) as
PACKAGIST_API_TOKEN. The safe token, which can only trigger package updates, is all the job uses. - Optionally, Packagist’s GitHub hook (offered on the package page after submission) so that pushes update the package without a release run; the job’s API call covers releases either way.
Verifying a release
Section titled “Verifying a release”curl -LO https://github.com/Netizine/sourceorrery/releases/download/vX.Y.Z/SHA256SUMScurl -LO https://github.com/Netizine/sourceorrery/releases/download/vX.Y.Z/sourceorrery-X.Y.Z-x86_64-unknown-linux-gnu.tar.gzsha256sum -c --ignore-missing SHA256SUMSgh attestation verify sourceorrery-X.Y.Z-x86_64-unknown-linux-gnu.tar.gz --repo Netizine/sourceorreryThe release job attests the build provenance of every file it attaches
(actions/attest-build-provenance, with id-token and attestations
permissions on that job only), in real releases only: an attestation is
public and permanent, so a dry run makes none. Release packages
re-uploads files the release already carries and attests nothing new.
What each registry adds on top (npm provenance, the Maven Central
signatures, nuget.org’s repository signature) and how a user checks it is
in Supply chain; signing the binaries themselves is on
the roadmap.