- docs
- Publish and integrate
- Publish and integrate
- Publishing
- Publish packages
Publish packages
Build an archive, attach metadata that declares its environment, and push both to any OCI registry.
The publisher journey
This section has a page for each step and for each decision around it. Follow the journey to the pages you need, or start with the first package at the end of this page. Most packages start as an upstream binary release on GitHub or a vendor’s download page. The pages below take you from “I have a binary” to “consumers can install it”, grouped by task.
Prepare the package
- Bundle a release: what goes in the archive, whether to repack the upstream layout and which compression to pick.
- Declare dependencies: when to depend on another package instead of bundling it, how to pin by digest and which edge visibility to use.
- Declare the environment: which variables to declare and how to mark each as
private,publicorinterface. - Add named launchers: when to ship launchers instead of exposing
bin/, and how to pick names that do not collide.
Check and push
- Test a package: run the install pipeline in a temporary directory, with no registry round trip and no new digest.
- Write script tests: assert on a package’s behavior with a Starlark script.
- Publish a package: the first push,
--cascadefor rolling tags and layer reuse by digest. - Publish for several platforms: push per platform under one tag and let OCX assemble the image index.
- Publish glibc and musl builds: publish Linux builds that differ by C library.
Make it resolvable
- Announce a package: claim the package once, then publish tags into the index on every release.
- Announce from CI: the credential postures for a GitHub or GitLab job, and who reviews what.
Secure and maintain releases
- Sign a release: keyless Sigstore signing from a laptop or CI, or a key pair instead.
- Attach attestations and SBOMs: attach an SBOM or another attestation to a package.
- Promote packages between environments: move a tested build from one registry to the next without rebuilding.
- Snapshot tracks: publish nightly or per-change builds and delete them again.
- Maintain patch companions: ship fixes on top of a published package.
Wrap tools you do not own
- Repackage an upstream release: turn a GitHub Release, Homebrew bottle or vendor archive into an OCX package, by hand or with
ocx-mirror.
Which page do I need?
Read the questions from the top. Each answer names the page to read next.
- What are you publishing? Your own build: Bundle a release. An upstream release you do not build: Repackage an upstream release.
- One platform or several? One: Publish a package. Several: Publish for several platforms. Linux builds that differ by C library: Publish glibc and musl builds.
- Who may publish? You, by hand: Announce a package. A CI job: Announce from CI, or the whole release pipeline in Publish packages from CI.
- How are releases tagged? Rolling tags that follow new releases: Publish a package. A tested build moved between registries: Promote packages. Nightly or per-change builds: Snapshot tracks.
- Must consumers verify what they install? The publisher: Sign a release. The contents: Attach attestations and SBOMs. Neither: you are done.
Publish your first package
You have a compiled binary, a Python script or any other executable, and you want consumers to run it after ocx package install. The path takes three steps, and Publish a package covers each one in detail.
First, lay out the working directory. The bundle contents live under build/, and the metadata sidecar sits next to it. The sidecar is not part of the archive. ocx package push uploads it as the OCI manifest config blob, and OCX restores it beside content/ at install time.
mytool/workdir (cwd for the commands below)build/bundle contents, which becomecontent/after installbin/mytoolyour binary, Python script or shell wrapper
metadata.jsonOCI config sidecar, not part of the archive
Second, write metadata.json with one public env entry that prepends the package’s bin/ to PATH:
{ "$schema": "https://ocx.sh/schemas/metadata/v1.json", "type": "bundle", "version": 1, "env": [ { "key": "PATH", "type": "path", "value": "${self.installPath}/bin", "visibility": "public" } ]}Third, bundle build/ into an archive and push it to a registry you can authenticate against. The push attaches metadata.json as the manifest config blob.
ocx login ghcr.ioocx package create build -p linux/amd64 -m metadata.json -o mytool-1.0.0.tar.xzocx package push -p linux/amd64 -m metadata.json \ -i ghcr.io/me/mytool:1.0.0 mytool-1.0.0.tar.xzConsumers reach the package with ocx package install ghcr.io/me/mytool:1.0.0, and the binary lands on their PATH once they pass --select or run ocx package select later, which makes the package current. ocx exec and ocx env put it on PATH without a select.
See also
- Metadata reference: every field and every constraint
- Command-line reference:
ocx packagecommands:create,push,pull,test,description pushanddescription pull - Storage: the object store that makes layer reuse work
- Environments: composition order, the edge filter and conflicting constants
- User guide: the consumer side of every decision documented here