oras-pants-plugin

A Pantsbuild plugin that publishes the output of pex_binary targets to OCI registries as OCI artifacts with oras. Any registry that stores OCI artifacts works: GitHub Container Registry, Docker Hub, Artifact Registry, ECR, ACR, Harbor, a local registry:2, and so on.

Installation

Add the plugin to pants.toml and enable its backend next to the Python backend:

[GLOBAL]
plugins = ["oras-pants-plugin==<version>"]
backend_packages.add = ["pants.backend.python", "oras_pants_plugin"]

Tell a pex_binary target where to push:

# src/app/BUILD
pex_binary(
    name="app",
    entry_point="main.py",
    oci_repositories=["ghcr.io/my-org/app"],
    oci_tags=["1.2.0", "latest"],
)

Then build and push it through the publish goal:

pants publish src/app:app

Pull it back anywhere with oras pull ghcr.io/my-org/app:1.2.0, which restores app.pex.

How it works

oras is downloaded as a static binary; nothing is installed into a Pants resolve. For every pex_binary target that lists oci_repositories, pants publish:

1. Packages the target as pants package would. A target without oci_repositories, with skip_oras=True, or run with [oras].skip = true is skipped before it is packaged.
2. Runs one oras push per oci_repositories entry, in the foreground so oras can show progress. Every artifact pants package produced for the target (the PEX, plus any scie executables) becomes a layer of one OCI artifact, which is tagged with every oci_tags entry at once. The manifest's artifactType is the target's oci_media_type.
3. Reports each push as published, failed or skipped, like every other publisher. --publish-output writes the same as JSON, with the repository and tags of each push.

A packed or loose layout PEX is a directory, which oras pushes as a gzipped tar layer and oras pull unpacks again. The layer media types are left to oras.

Target fields

Configuration

Credentials

oras reads the credentials that docker login or oras login store in $DOCKER_CONFIG/config.json or ~/.docker/config.json, and runs the credential helpers configured there. PATH, HOME and DOCKER_CONFIG are always passed to oras, so logging in once is enough:

oras login ghcr.io          # or: docker login ghcr.io
pants publish src/app:app

In CI, pass the token to a login step before pants publish, or point [oras].args at an auth file with --registry-config. Avoid --username/--password in pants.toml: the file is committed.

Pushing to a directory

oras can write to an OCI image layout directory instead of a registry, which is handy for inspecting what would be pushed:

pants --oras-args="['--oci-layout-path', '/tmp/app-layout']" publish src/app:app

The reference in oci_repositories is kept as the tag name inside the layout.

Using a different oras version

Add the release's checksums and sizes to known_versions and set version:

[oras]
version = "1.3.5"
known_versions.add = [
  "1.3.5|linux_arm64 |<sha256>|<size>",
  "1.3.5|linux_x86_64|<sha256>|<size>",
  "1.3.5|macos_arm64 |<sha256>|<size>",
  "1.3.5|macos_x86_64|<sha256>|<size>",
]

Compute each line with curl -L $URL | tee >(wc -c) >(shasum -a 256) >/dev/null, where $URL is the oras_<version>_<os>_<arch>.tar.gz asset of the GitHub release (linux/darwin, amd64/arm64). The release's oras_<version>_checksums.txt lists the same checksums.

Supported versions

Pants loads plugins into its own interpreter, so the plugin requires the Python version Pants runs on. The PEX being published may target any Python version.

Releases

Wheels are published to PyPI. Release notes live in the changelog and on the GitHub releases page.

Contributing, Bug Reports and Feature Requests

This plugin lives in the pants-plugin-depot repo. See its CONTRIBUTING.md, or open an issue.