Publishing means adding an immutable version entry (and, for small packages, the archive) to the registry repository, signed by a key the registry knows for your publisher id.
Self-service publishing#
Publishing is a pull request to the registry repository, and every step that can be automated is.
- Register as a publisher (once). Create a key, then:
bash arcotheon keys generate acme-publisher arcotheon registry publisher register acme --name "Acme Ltd" --key acme-publisher --github acme-inc --root registry
This writes registry/publishers/acme.json containing your public key and a signature proving you hold it. Open a pull request with only that file. Automated review checks the id, the reserved-name list, the proof and that you did not grant yourself trusted; a maintainer then verifies who you are and merges.
- Publish a version. From your capability directory:
bash arcotheon publish . --key acme-publisher --submit --repo sarja-technologies/arcotheon
This clones the registry, builds and signs your package, writes the entry and archive, runs the same review CI runs, pushes a branch and opens the pull request. (Or run publish --registry-dir against your own checkout.)
- Automated review (
arcotheon registry check-changes, run by CI and runnable locally) rejects a change that modifies or deletes a published entry, publishes for a publisher not already registered at the base commit, uses a key not listed for that publisher at the base commit (a pull request cannot vouch for its own key), has an archive that is missing, mismatched, unsigned, or larger than 5 MiB, or tries to self-assign trust. Changes to the signed catalogue, status files, root keys and existing publishers are routed to a maintainer. - Release. A maintainer merges, rebuilds and signs the catalogue (see production signing), and the release assets and directory update.
The repository is currently private, so outside contributors cannot open these pull requests yet. Making it public (or running a separate public submission repository) is a maintainer decision.
Large content#
Archives in Git are limited to 5 MiB. Larger things are resources: upload them to object storage with arcotheon storage push <file> --endpoint … --bucket … (resumable multipart above 64 MiB, --verify re-hashes the stored object), then reference the printed sha256, size and URL in the manifest's resources.
Versioning rules#
- Semantic versions. A prerelease suffix marks a prerelease and is hidden from default resolution.
- Never edit a published version. Publish a new one; yank or revoke the bad one with a reason.
- Put the version's notes in
CHANGELOG.mdunder## <version>; the registry shows them on the version's page. - Adding permissions is allowed but every installed user is asked again. Removing them is free.
Paid or private capabilities#
Set distribution: { tier: "pro", access: "entitled", entitlement: "<key>" }. The catalogue entry stays public. Hosting the archive behind an authorisation is up to the publisher and the host; the registry only records the requirement.
Not built yet#
- Fully automated publishing from a publisher's own GitHub Actions with short-lived OIDC identities bound to a publisher, and a signing service that signs only after the checks pass.
- A web submission form on the directory.
- Static analysis of tool code against declared permissions, and malware scanning.