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
| Label | Required | Value |
|---|---|---|
com.yardrail.workflow.spec | yes | "v1" (the only recognized version) |
com.yardrail.workflow.name | yes | Display name for the catalog (e.g. "Daily Sales Summary") |
com.yardrail.workflow.slug | no | URL-safe identifier (e.g. "daily-sales-summary") |
com.yardrail.workflow.description | no | Short description |
com.yardrail.workflow.category | no | Marketplace category (e.g. "retail") |
com.yardrail.workflow.version | no | Semver 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
registryscan.Service.ScanOrglists all repositories in the org's configured registries viacrane.Catalog- For each repository,
crane.ListTagsenumerates tags - Each tag is passed to
pkg/workflows.ParseArtifact(ref), which:- Fetches the image config (not a full pull)
- Reads the
com.yardrail.workflow.specandcom.yardrail.workflow.namelabels - Walks each layer as a tar archive looking for the
workflow.cwlentry
- Images missing the required labels are silently skipped — most images in a general-purpose registry aren't workflow artifacts
- Valid artifacts are upserted as
workflow_templatesrows in the org's catalog
Install flow
When a user installs a workflow from a template:
- The source registry is resolved (Depot-managed via
"depot:"prefix or user-added via"registryscan:"prefix) ParseArtifactpulls the image config + CWL layer- The raw CWL bytes are stored as the workflow installation's
scriptfield ExtractInputFieldsparses the CWL to build the trigger-input schema