Skip to main content

OCI Artifacts

A Yardrail workflow is distributed as a standard OCI image — a FROM scratch container with the CWL document at a known path and metadata in image labels. The platform discovers these artifacts by scanning configured registries and extracting the workflow definition from any image that carries the required labels.

Artifact spec (v1)​

Image labels​

LabelRequiredValue
com.yardrail.workflow.specyes"v1" (the only recognized version)
com.yardrail.workflow.nameyesDisplay name for the catalog (e.g. "Daily Sales Summary")
com.yardrail.workflow.slugnoURL-safe identifier (e.g. "daily-sales-summary")
com.yardrail.workflow.descriptionnoShort description
com.yardrail.workflow.categorynoMarketplace category (e.g. "retail")
com.yardrail.workflow.versionnoSemver version string (e.g. "1.0.0")

CWL file location​

The CWL document must be at workflow.cwl at the root of the image filesystem — a tar entry named workflow.cwl with no leading slash or subdirectory. The constant is WorkflowCWLPath in pkg/workflows/artifact.go.

The file can be in any layer — all layers are searched sequentially.

Dockerfile​

FROM scratch
LABEL com.yardrail.workflow.spec=v1
LABEL com.yardrail.workflow.name="Daily Sales Summary"
LABEL com.yardrail.workflow.slug=daily-sales-summary
LABEL com.yardrail.workflow.description="End every day with a clean sales recap"
LABEL com.yardrail.workflow.category=retail
LABEL com.yardrail.workflow.version=1.0.0
COPY workflow.cwl /workflow.cwl

No OS layer, no entrypoint — just the labels and the CWL file. Additional layers (model weights, static assets) are fine; only workflow.cwl is extracted.

Build and push​

Using the yr CLI​

The yr artifact build command validates the Dockerfile labels and CWL document, builds the image, and optionally pushes it:

yr artifact build . --registry registry.example.com/org/my-workflow:1.0.0 --push

Inspect an already-pushed artifact:

yr artifact inspect registry.example.com/org/my-workflow:1.0.0

Using Docker directly​

docker build -t registry.example.com/org/my-workflow:1.0.0 .
docker push registry.example.com/org/my-workflow:1.0.0

For local development with the Docker Compose stack, push to your configured registry:

docker build -t registry.local/yardrail/my-workflow:latest .
docker push registry.local/yardrail/my-workflow:latest

Discovery flow​

  1. registryscan.Service.ScanOrg lists all repositories in the org's configured registries via crane.Catalog
  2. For each repository, crane.ListTags enumerates tags
  3. Each tag is passed to pkg/workflows.ParseArtifact(ref), which:
    • Fetches the image config (not a full pull)
    • Reads the com.yardrail.workflow.spec and com.yardrail.workflow.name labels
    • Walks each layer as a tar archive looking for the workflow.cwl entry
  4. Images missing the required labels are silently skipped — most images in a general-purpose registry aren't workflow artifacts
  5. Valid artifacts are upserted as workflow_templates rows in the org's catalog

Install flow​

When a user installs a workflow from a template:

  1. The source registry is resolved (Depot-managed via "depot:" prefix or user-added via "registryscan:" prefix)
  2. ParseArtifact pulls the image config + CWL layer
  3. The raw CWL bytes are stored as the workflow installation's script field
  4. ExtractInputFields parses the CWL to build the trigger-input schema