Building a CodeCollection Image

Every CodeCollection image follows the same pattern: FROM rw-base-runtime, copy the codecollection contents, install pip dependencies. Here’s the reference Dockerfile from rw-cli-codecollection:

ARG BASE_IMAGE=ghcr.io/runwhen-contrib/rw-base-runtime:latest
FROM ${BASE_IMAGE}

USER root
ENV RUNWHEN_HOME=/home/runwhen

RUN mkdir -p $RUNWHEN_HOME/collection
WORKDIR $RUNWHEN_HOME/collection

COPY --chown=runwhen:0 . .

RUN if [ -f "requirements.txt" ]; then \
      pip install --no-cache-dir -r requirements.txt; \
    fi

RUN echo "runwhen ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
RUN mkdir -p /var/tmp/runwhen && chmod 1777 /var/tmp/runwhen
ENV TMPDIR=/var/tmp/runwhen

RUN chown runwhen:0 -R $RUNWHEN_HOME/collection
USER runwhen

Path convention

Codecollection contents must land at /home/runwhen/collection — not /codecollection or any other path. PAPI emits RW_PATH_TO_ROBOT=$(RUNWHEN_HOME)/collection/codebundles/... and the runrobot.{sh,py} helper scripts only resolve paths under /home/runwhen/collection. A mismatch surfaces as:

FileNotFoundError: Could not find the robot file in any known locations.

Pinning the base image

Override BASE_IMAGE at build time to pin a specific runtime commit:

docker build \
  --build-arg BASE_IMAGE=ghcr.io/runwhen-contrib/rw-base-runtime:<sha7> \
  -t my-codecollection:dev .

The CI workflow (.github/workflows/build-push.yaml in each codecollection repo) resolves the runtime_ref dispatch input to an rw-base-runtime commit SHA and bakes that SHA into the resulting image tag suffix.

CI pipeline

CodeCollection images are built in GitHub Actions, not locally:

1. Pull requests → build test only (no push)
2. Push to main → multi-arch build (linux/amd64 + linux/arm64) → push to GHCR and GCP Artifact Registry

Tag schema

CodeCollection images use a composite tag that encodes provenance:

<ref>-<cc_sha>-<rt_sha>

Component	Meaning
<ref>	Git ref (branch name or tag)
<cc_sha>	CodeCollection commit SHA (first 7)
<rt_sha>	rw-base-runtime commit SHA (first 7) — which runtime the image was built against

This lets PAPI and the registry’s CCV catalog always determine which runtime a given codecollection image was built from.