Create or update (upsert) an image index?

[polarathene]

I noticed that oras manifest index has create and update subcommands, but it seems there is no support to perform something like an "upsert"? (update or fallback to create), which apparently docker buildx imagetools create supports via --append (I've only read about that expectation from someones GHA workflow, not yet verified).

Should I open a new feature request about that?

• create replaces any existing index.
• update requires the index to already exist.

[polarathene]

Slightly off-topic: I'm looking into how to manage CI builds that only push the images to a registry and require stitching those together for tagging as a follow-up, which AFAIK needs to be done manually and oras manifest / docker buildx imagetools create commands would perhaps be suitable for that?

Seems simple enough for multi-arch, but I'm not sure about when it's more than one image index and set of tags.

Real-world context

Perhaps in my case, since I need to construct an index with different tags per image (which include tagged image variants), it would be better to construct locally with an OCI image layout followed by oras manifest push (not quite sure if that's compatible, the docs focus on image manifests rather than indexes for this command).

I have a workflow that builds images via a matrix in Github Actions, not just different archs of the same image but variants. They're all pushed to the same registry by digest/manifest only, where after completion I'd like to construct the multi-arch multi-platform image index (linux/amd64, linux/arm64, windows/amd64).

When this is all built on the same build host it's all handled by docker build or similar to produce and push the image index along with the image manifests.

With separate images that would otherwise have all the same tags and only differ by arch this is a single image index with each tag pointing to the image index which has the different arch/platforms associated to it AFAIK.

So for separate runtime and builder images, I could build these two together on the same CI runner / build host per arch, but that complicates tagging a bit. A similar situation for Windows images which while using the same arch differ by their release channel (LTSC 2022 + LTSC 2025, and base image variants), a Windows client presumably knows how to pick the right LTSC variant (there's annotated version information alongside the platform and arch) while the windows base image variants are via tag.

docker.io/library/caddy:latest for example seems to have all of these within the same index, while some share tags (latest across the runtime Linux Alpine image and two Windows LTSC images, builder for equivalent builder image variant) along with unique tags (builder-alpine, 2.10-builder-alpine).

oras manifest fetch docker.io/library/caddy:latest | jq . | less

---

Advice for approaching

Would you create an index in advance before the matrix and update it within each CI runner build instance via oras? An empty image index would always have the same digest to reference it I think? (as opposed to a tag) Associating a tag at this point doesn't seem wise if it's not a new tag?

Or wait until all builds are done and pushed before updating the registry to point the images to tags (I have a JSON object with each image variant, it's own image index digest (I think) and tags).

It seems like this might be simpler to construct the image index locally? I mentioned the OCI layout, but that requires the relevant image manifests in that layout too IIRC, so perhaps I would be interacting with the image registry (GHCR) and output one or more image indexes locally with --output to merge + oras manifest push?

I have done the following with Caddy as practice for example (acquiring the two manifests via oras cp ...):

# Copy from registry to local OCI layout with tag `2`:
# Despite the upstream image index when copying individual images by platform like this
# it copies the image manifests only, thus they cannot both be associated to tag `2`?
oras cp docker.io/library/caddy:2 --to-oci-layout oras-caddy:2 --platform linux/amd64
oras cp docker.io/library/caddy:2 --to-oci-layout oras-caddy:2 --platform linux/arm64

# As these are image manifests (amd64 + arm64 image archs) not image index, the tags get reassigned:
oras tag --oci-layout oras-caddy@sha256:5c18f4b845cd8f2cbb344ffa6fe0391d8c975ed921848c9968298f1eb8940a97 \
  latest 2
oras tag --oci-layout oras-caddy@sha256:3ec909d297a11a136cd78a90765e157967466bc0c19b99cd884d0479c563a1dc \
  latest 2

# Only the last tagged image manifest will be output:
oras manifest fetch --oci-layout oras-caddy:latest

I can use oras manifest index create to create a new image index (and optionally associate it to tags) and choose image manifests to include. I'm not sure if this would have equivalent support to the image index merge feature that oras manifest index update has.

# Creates an image index (`index.json`) at the OCI layout location `./oras-caddy`
# Then for tags `latest` and `2` adds the image manifests (linux/amd64 + arm64)
# With the two tags referencing this image index (`oras-caddy/blobs/sha256/...`)
# at the `index.json`.

oras manifest index create --oci-layout oras-caddy:latest,2 \
  sha256:3ec909d297a11a136cd78a90765e157967466bc0c19b99cd884d0479c563a1dc \
  sha256:5c18f4b845cd8f2cbb344ffa6fe0391d8c975ed921848c9968298f1eb8940a97

Perhaps only the manifests are necessary without pulling a full copy of images into the OCI layout? Otherwise I'll focus on interacting with the image registry directly.

---

Docker documents an example with their own docker buildx imagetools create:

# `docker/metadata-action` outputs tags JSON via ENV, `jq` processes this into `--tag` / `-t` args
# for the command to create an image index for that the tags will reference.
# Then the `printf` is providing a list of image refs by digest to use using the files at the working directory as input for the digest values
- name: Create manifest list and push
  working-directory: ${{ runner.temp }}/digests
  run: |
    docker buildx imagetools create \
      $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
      $(printf '${{ env.REGISTRY_IMAGE }}@sha256:%s ' *)

I've yet to give that a whirl, but can see parallels with oras for creating an image index for a set of digests and tags to associate.

• In the latest + builder shared tags, I assume I'd invoke a command like this twice, once for each image variant with it's archs and tags.
• The platform/variant specific tags (eg: alpine, windowsservercore-ltsc2022, windowsservercore-ltsc2025) presumably are separate image indexes and thus commands too?
  Seems like it: oras manifest fetch docker.io/library/caddy:alpine | jq . | less
  • Config that represents variants to build/publish.
  • Config built from that prior config with full tagging generated
    Each block of config there is presumably it's own image index with all it's Tags referencing it, while the SharedTags would be additional image indexes such as multi-platform latest/builder tags?

I guess in the case of the Caddy config above, the distinction of Tags/SharedTags is useful and if all archs are built on the same build host letting it push/publish those Tags would be fine, while oras would be required for stitching together the SharedTags from separate runners?