Publishing to the Xema Store

The Xema Store lets your biome reach any Xema organization. This page covers the full publishing flow — from a locally validated biome to a store-approved listing.

The four Store capabilities

Capability	Who uses it	What it does
`store:biome.list@1`	Anyone	Browse published listings — the only Store capability granted by default
`store:biome.submit@1`	Biome author	Submit a biome for review
`store:biome.approve@1`	Xema store reviewer	Approve a submitted biome
`store:biome.archive@1`	Author or reviewer	Archive a published listing

You need store:biome.submit@1 to publish. It is not granted by default — the only Store capability every authenticated user holds out of the box is the catalog read, store:biome.list@1. Ask an organization administrator to grant store:biome.submit@1 before you submit; without it, every submit call is refused.

The publishing flow

text

1local draft
2    ↓  xema biome submit
3store-submitted   (Xema runs automated tests; SBOM generated; manifest inspected)
4    ↓  reviewer approves via store:biome.approve@1
5store-approved    (visible to all orgs)

1. Bundle and sign

bash

1COSIGN_KEY=cosign.key xema biome publish ./acme-code-review \
2  --registry ghcr.io/acme --token-env GHCR_TOKEN

This packages the biome tree as an OCI artifact (artifactType application/vnd.xema.biome.manifest.v1+json, one layer per file), pushes it, and signs the pushed ref with cosign. Signing is the publisher's job and is mandatory — the publish fails before pushing if COSIGN_KEY is unset, and the platform refuses to install an unsigned artifact. The signature is pinned in the Store listing.

Everything under the biome root ships except node_modules/ and .git/ — manifest, source, compiled output and contributions alike. See SDK — Publishing for the full format and flag reference.

2. Submit

bash

1xema biome submit ./dist/acme-code-review-1.2.0.tar.gz \
2  --store-category "developer-tools" \
3  --listing-page ./store-listing.md

Or through the Biome Studio UI: Store → Submit Biome → Upload Bundle.

The submission creates a store-submitted entry. Automated checks run immediately:

Manifest schema validation
SBOM generation
Capability risk scoring
Sandbox execution tests (your biome installs and runs in a store-review environment)

3. Review

A Xema store reviewer inspects the automated report, checks the sandbox execution results, and reviews the permission digest. Review time depends on capability risk:

Risk tier	Typical review time
`low` (read-only, no connectors)	1–2 business days
`medium` (write capabilities, internal connectors)	3–5 business days
`high` (external connectors, schema migrations)	7–10 business days

4. Approval

When approved, the biome moves to store-approved. The Store listing becomes visible to all orgs. Orgs can then find it in the catalogue. Installation goes through biome lifecycle: the host plans the install, you review the plan, and it applies exactly what was planned. The Store is a catalogue you browse and publish to; it does not install.

Versioning

The Store treats version in xema-biome.json as the canonical version. Semantic versioning is enforced:

Patch (1.0.0 → 1.0.1): bug fixes, documentation updates, no manifest changes. Fast-tracked by automated checks.
Minor (1.0.0 → 1.1.0): new contributions, new optional capabilities. Full review.
Major (1.0.0 → 2.0.0): breaking changes to capability refs, storage schema migrations, removed contributions. Full review + capability diff.

Submit a new version with the same name and an incremented version. The Store keeps all prior versions available for orgs running pinned installs.

OCI packaging and SLSA

Biome bundles are stored as OCI artifacts in a container registry. Each bundle carries a cosign signature on the pushed ref, plus a SLSA v1.0 in-toto attestation (predicateType https://slsa.dev/provenance/v1) attached with cosign attest.

biome-fetcher-api verifies both before any bytes are unpacked, against the trust anchors in BIOME_TRUSTED_PUBLISHERS. A missing signature, an untrusted signer, or a missing/invalid attestation is a typed BIOME_* failure and a 403 — the install never proceeds. To check an artifact yourself:

bash

1cosign verify --key cosign.pub ghcr.io/acme/acme-code-review:1.2.0
2cosign verify-attestation --key cosign.pub \
3  --type https://slsa.dev/provenance/v1 \
4  ghcr.io/acme/acme-code-review:1.2.0

See Biome supply-chain security for the operator runbook.

Updating a published listing

To update metadata (description, listing page, screenshots) without incrementing the version, edit the listing in the Store (there is no xema CLI command for it).

Listing metadata updates go through a lightweight review (no sandbox run required). Capability changes always require a version bump and full review.

Previous: ← Authoring

Next: Manifest Reference →