registry

pkg/registry

The registry package implements the Orkestra artifact registry — an OCI-based store for patterns (Katalog-based operators) and motifs (reusable resource primitives) that can be pushed, pulled, and listed by the ork registry CLI commands.

Artifact kind is detected automatically from the primary YAML file (kind: Katalog → pattern, kind: Motif → motif). No separate code path per kind is needed — adding a new artifact kind is a one-line entry in artifactSpecs in artifact.go.

What this package provides

Artifact kinds

Pattern (kind: Katalog)

A Katalog-based operator pattern. Required files: katalog.yaml, crd.yaml.

my-operator/
  katalog.yaml   application/vnd.orkestra.katalog.v1+yaml       (required)
  crd.yaml       application/vnd.kubernetes.crd.v1+yaml         (required)
  README.md      text/markdown                                   (optional)
  cr.yaml        application/vnd.kubernetes.cr.v1+yaml          (optional)

Manifest media type: application/vnd.orkestra.pattern.v1+tar+gzip
Default registry: ghcr.io/orkspace/orkestra-registry/patterns
Override: ORK_REGISTRY

Motif (kind: Motif)

A reusable resource primitive (stateful service, shared infrastructure). Required file: motif.yaml.

my-motif/
  motif.yaml     application/vnd.orkestra.motif.v1+yaml         (required)
  README.md      text/markdown                                   (optional)
  example/       (directory)                                     (optional)

Manifest media type: application/vnd.orkestra.motif.v1+tar+gzip
Default registry: ghcr.io/orkspace/orkestra-motifs
Override: ORK_MOTIFS_REGISTRY

Push flow

ValidateArtifactDirectory(dir)   — detect kind, check required files, list all files
LoadArtifactMeta(dir, spec)      — read name/version/description from primary YAML
    ↓
client.Push(ctx, ref, dir)
    → read each file into memory store (nothing written back to dir)
    → oras.Pack  — manifest with kind-specific media type and artifact annotations
    → store.Tag  — register manifest under ref.Tag
    → oras.Copy  — push all blobs + manifest to remote
    → updateIndex — upsert entry into index:latest (best-effort)

Additional validation layers run in the CLI before client.Push is called (see docs/04-patterns.md).

Annotations

Every manifest carries standard OCI annotations derived from the artifact's primary YAML:

Info reads these annotations to reconstruct metadata without downloading any files. The legacy io.orkestra.pattern.* keys are still read for backward compatibility with artifacts pushed before the generic artifact layer.

Index artifact

ork registry list reads a single index:latest artifact from the registry namespace root. Each registry has its own index:

• Patterns: ghcr.io/orkspace/orkestra-registry/patterns/index:latest
• Motifs: ghcr.io/orkspace/orkestra-motifs/index:latest

Push automatically updates the index after every successful push. If the index push fails it is logged as a warning — the artifact push is not rolled back.

Reference resolution

Resolve routes bare names to the pattern registry (for backward compatibility). ResolveForKind picks the correct registry based on detected kind:

// Pattern
ref, err := registry.ResolveForKind("postgres:v1", registry.KatalogKind)
// → ghcr.io/orkspace/orkestra-registry/patterns/postgres:v1

// Motif
ref, err := registry.ResolveForKind("redis:v7", registry.MotifKind)
// → ghcr.io/orkspace/orkestra-motifs/redis:v7

// Full OCI ref — used as-is regardless of kind
ref, err := registry.ResolveForKind("oci://ghcr.io/myorg/motifs/redis:v7", registry.MotifKind)
// → ghcr.io/myorg/motifs/redis:v7

Authentication

Reads ~/.docker/config.json via credentials.NewStoreFromDocker. Run docker login ghcr.io before pushing. No separate ork registry login command.

Developer documentation