Composition

Orkestra has two composition primitives: imports and include. They solve different problems and operate at different scopes.

Aggregators

Every Orkestra kind has a corresponding aggregator kind that composes multiple instances of it into one operation:

Motif has no aggregator — it is the reusable unit, not the runner. It is consumed by Katalogs and Komposers via imports:.

The two primitives

imports: — cross-unit reuse

imports: brings in content from a separate artifact: a Motif, another Katalog, an OCI image, a Helm chart, an E2E file, a Simulate file. The imported unit has its own path, its own version, and potentially its own author. It may live in a different repository.

Use imports: when:

• A concern is shared across multiple operators or teams
• You want to version and distribute the concern independently
• The imported unit has its own lifecycle (update it without touching the importing Katalog)

→ imports in depth

include: — file splitting

include: references a file in the same directory. Both files are loaded together as one logical unit — the include file is not an artifact, has no version, and is invisible after expansion. It is authoring ergonomics, not reuse.

Use include: when:

• A Katalog, Motif, E2E, or Simulate file is getting long
• You want to split a block (validation rules, status fields, notes, ops assertions) into a focused file
• Test katalog variants share a common block without a Motif dependency

→ include in depth

Reference