Publishing

There are two publications

This page is about the image — building it and pushing it to a container registry. Publishing the contract to the catalogue, for other people to find and use, is a different thing, and lives in The portal.

The order matters: the image first. The portal does not check that it exists, and publishing the contract first leaves whoever consumes it with an oren install that fails.

During development, the implementation builds from the local directory:

runtime:
  type: container
  build:
    context: ./worker

That is not publishable — whoever consumes it needs the finished image, not the source. A CI job does not have your directory either, so oren generate refuses implementations like this.

Publishing

docker build -t ghcr.io/youraccount/oren-my-task-alpine:1.0.0 worker/
docker push ghcr.io/youraccount/oren-my-task-alpine:1.0.0

runtime:
  type: container
  image: ghcr.io/youraccount/oren-my-task-alpine:1.0.0

oren install    # resolves the tag to a digest

With the image up, the contract goes to the catalogue:

oren publish .

The name carries the engineering choice

The repository should reflect the implementation, not the task:

oren-build-docker-image-kaniko
oren-push-docker-image-skopeo
oren-analyze-commits-alpine

The suffix makes it evident that this is one way of satisfying the contract. Someone publishes -buildkit and the two coexist in the catalogue, comparable by the privilege they require. Named after the task, it would look like the implementation.

One image can serve several tasks

terraform-plan and terraform-apply are different contracts — different effects, outputs and dependencies — but use the same binary. Both implementations point at the same image and pick the script by entrypoint:

runtime:
  image: ghcr.io/acme/oren-terraform-hashicorp:1.0.0
  entrypoint: ["/worker/plan.sh"]

A subcommand is an entrypoint, and the implementation is what chooses it — not an input of the contract. Merging the two into one contract with a command field would force declaring the worst case in effects, losing the information that planning is safe to repeat.

A published version is immutable

Republishing a version with different content breaks whoever depends on it, with no signal — and silently transfers the access authorisation someone granted to the previous version.

To publish again, bump the implementation’s version.