- docs
- Publish and integrate
- Publish and integrate
- Publishing
- Repackage an upstream release
Repackage an upstream release
By the end of this page you have an upstream release repackaged as an OCX package. Upstream projects usually ship binaries as a Homebrew formula, a GitHub Release zip, an APT repository or a signed installer. You reformat those artifacts into OCI image manifests without re-bundling content. You need the upstream asset and a metadata.json. The ocx-mirror tool automates the recurring steps.
The ocx-mirror pipeline
ocx-mirror keeps public OCX packages in sync with their upstreams. A YAML spec says where to find releases, which assets to take per platform and how to map them onto OCX metadata. The tool then runs download, bundle and push, the same steps as the ocx package commands.
Compared with running the commands by hand, the pipeline batches --cascade resolution across platforms in one invocation and transforms upstream archives deterministically. A versions.new_per_run limit (unlimited when omitted) stops one CI run from flooding the registry with a backlog. ocx-mirror always uploads each platform’s archive afresh, so the layer-reuse pattern applies only to hand publishing.
A minimal spec that wraps one upstream project:
name: mytooltarget: registry: ocx.sh repository: mytool
source: type: github_release owner: example-org repo: mytool tag_pattern: "^v(?P<version>\\d+\\.\\d+\\.\\d+)$"
assets: linux/amd64: - "mytool-.*-linux-x86_64\\.tar\\.gz" linux/arm64: - "mytool-.*-linux-aarch64\\.tar\\.gz"
asset_type: type: archive strip_components: 1
metadata: default: metadata.jsonInstall the tool with ocx --global add ocx.sh/ocx/mirror. The binary is ocx-mirror. Validate the spec, preview a run, then sync the newest release:
ocx-mirror package validate mirror.ymlocx-mirror package check mirror.ymlocx-mirror package sync mirror.yml --latestvalidate never touches the network, and check lists what a real run would push without pushing it. sync reuses the registry credentials of docker login and ocx login. The ocx-mirror getting-started guide walks through the same flow with a worked example.
cascade defaults to true. Set cascade: false only for repositories that must not advance rolling tags. This excerpt of the astral-sh/uv mirror spec adds a multi-platform asset matrix, version-range filtering and per-platform metadata overrides:
name: uvtarget: registry: ghcr.io repository: ocx-contrib/astral-sh/uv
source: type: github_release owner: astral-sh repo: uv tag_pattern: "^(?P<version>\\d+\\.\\d+\\.\\d+)$"
# Multi-platform asset matrix: each platform lists one or more regexes;# the union must resolve to exactly one asset filename per release.assets: "linux/amd64+libc.glibc": - "^uv-x86_64-unknown-linux-gnu\\.tar\\.gz$" linux/amd64: - "^uv-x86_64-unknown-linux-musl\\.tar\\.gz$" darwin/arm64: - "^uv-aarch64-apple-darwin\\.tar\\.gz$" windows/amd64: - "^uv-x86_64-pc-windows-msvc\\.zip$"
# The Windows zip has no wrapper directory, so it strips nothing.asset_type: default: type: archive strip_components: 1 platforms: windows/amd64: type: archive strip_components: 0
# Per-platform metadata overrides for a non-trivial upstream.metadata: default: metadata.json platforms: windows/amd64: metadata-windows.json
# Version-range filtering: only mirror releases >= 0.10.0, max 5 per run.versions: min: "0.10.0" new_per_run: 5Repackaging GitHub Releases
The github_release source type reads the release feed, downloads the assets that match each platform regex and pushes them. By hand, a few curl calls and a script give the same flow. ocx-mirror adds deterministic ordering across runs and a digest-verification slot, verify.github_asset_digest.
The platform regex matrix is the part publishers re-derive most often. This excerpt of the uv mirror spec gives the glibc build and the static musl build of one release their own platform keys:
"linux/amd64+libc.glibc": - "^uv-x86_64-unknown-linux-gnu\\.tar\\.gz$"linux/amd64: - "^uv-x86_64-unknown-linux-musl\\.tar\\.gz$"The pipeline applies every regex and requires the matches to resolve to exactly one asset filename per release. Two regexes that match the same filename are fine. Two that match different filenames abort with Ambiguous. The full uv example shows the whole matrix.
Repackaging a release asset by hand
A release tarball usually wraps its content in a version-named directory such as mytool-1.2.3-linux-x86_64/bin/mytool. OCX bundles need a flat root. --extract bundles the downloaded asset directly, so you skip unpacking, stripping the wrapper and re-tarring. Here the downloaded release asset itself is the archive to bundle, and its single wrapper directory is stripped on the way in:
curl -LO https://github.com/example-org/mytool/releases/download/v1.2.3/mytool-1.2.3-linux-x86_64.tar.gzocx package create mytool-1.2.3-linux-x86_64.tar.gz \ --extract --strip-components 1 -m metadata.json \ -i ghcr.io/acme/mytool:1.2.3 -p linux/amd64 \ -o mytool-1.2.3-linux-amd64.tar.xzPush the bundle. The build receipt next to it supplies the identifier and platform. A successful push prints a one-row table and exits 0:
ocx package push mytool-1.2.3-linux-amd64.tar.xzIdentifier Digest Tags Keep Tags Layersghcr.io/acme/mytool:1.2.3 sha256:<hex> 0 mounted=0,uploaded=1,verified=0Confirm that the registry lists the platform with ocx index list:
ocx --remote index list --platforms ghcr.io/acme/mytool:1.2.3Publish a package covers authentication and rolling tags for this push.
--extract unpacks the asset into a temporary directory and bundles that tree. The metadata sidecar, the binaries scan and the libc check all run against the extracted content.
Extraction is capped at the larger of 100 times the compressed size and 256 MiB. The cap is not configurable. --strip-components runs once, on the upstream asset, at authoring time. The metadata strip_components field is a different mechanism that applies on every consumer’s install. Two strip_components, two different moments explains how they relate.
Repackaging Homebrew formulae
Homebrew formulae are Ruby programs, not declarative manifests. Each one encodes its own download URL, build steps and install hook, so no general “import a formula” path exists. Read the formula’s bottle do ... root_url ... sha256 ... end block for binary bottles, or its url and sha256 for source releases. Mirror those bytes through a github_release-shaped pipeline or fetch them directly. Then write a metadata.json that covers the env entries Homebrew’s post-install script would have set.
Binary bottles unpack as <formula>/<version>/bin/..., so strip_components: 2 fits the usual layout. Add a PATH env entry with "visibility": "public" (the default is private) so consumers see the binaries. Source-built formulae do not repackage without a rebuild, since OCX distributes binaries.
Attaching description metadata
After the package is in the registry, ocx package description push attaches a README, logo, title, keywords and short description. The fields are stored as an OCI image manifest under the internal tag __ocx.desc. They travel with every registry export and feed the package catalog. ocx package description pull reads them back, and --save-readme writes the published markdown to disk for diffing.
ocx package description push \ --readme README.md \ --logo logo.svg \ --title "mytool" \ --description "A small example tool" \ --keywords cli,linting \ acme/mytoolocx package description pull acme/mytoolSee also
ocx package description pushreferenceocx package description pullreference- Publish a package for pushing by hand
- Announce a package to list it in an index