Inheritance & Worked Example

Both connections and environments support extends: for composition.

Connection inheritance — a base template

extends: on a connection is a base-template pattern. Define the shared fields once:

connections/akeneo-base.connection.yaml

type: zenvara/akeneo
kind: base
TimeoutSeconds: 120
BatchSize: 100
MaxConcurrency: 4
AutoSanitizeCodes: true

# connections/akeneo-pim-prod.connection.yaml
type: zenvara/akeneo
kind: production
extends: akeneo-base
BaseUrl: "https://prod.cloud.akeneo.com"
ClientId: "${secret:akeneo/pim-prod/client-id}"
ClientSecret: "${secret:akeneo/pim-prod/client-secret}"
Username: "${secret:akeneo/pim-prod/username}"
Password: "${secret:akeneo/pim-prod/password}"

kind: and type: are required on every connection file — including a child that extends: a base — because they’re validated before inheritance is resolved (each file must independently declare the same type: as its parent). kind: base marks a template as extends-only: it is never bound directly into an environment and only a kind: base connection may be extends:ed.

Three overrides plus one base, instead of four near-identical files.

Environment inheritance

extends: on an environment is a list of parent environments composed in order — single-level only (no transitive chains), to keep the resolution graph easy to read.

environments/staging.environment.yaml

kind: staging
extends:
  - common
connections:
  db:
    connection: warehouse-staging   # overrides whatever `common` had under db

Worked example: dev → prod for one flow

Two connections (one Postgres, one SFTP), two environments, one flow:

connections/audit-postgres-base.connection.yaml

type: zenvara/postgresql
kind: base
TimeoutSeconds: 30

# connections/audit-postgres-dev.connection.yaml
type: zenvara/postgresql
kind: development
extends: audit-postgres-base
ConnectionString: "${secret:audit/dev:connection-string}"

# connections/audit-postgres-prod.connection.yaml
type: zenvara/postgresql
kind: production
extends: audit-postgres-base
ConnectionString: "${secret:audit/prod:connection-string}"

# environments/dev.environment.yaml
kind: development
connections:
  audit:
    connection: audit-postgres-dev
  drop:
    connection: drop-zone-dev

# environments/prod.environment.yaml
kind: production
connections:
  audit:
    connection: audit-postgres-prod
  drop:
    connection: drop-zone-prod

flows/incident-archive.flow.yaml

status: active

using:
  - environment/dev
  - environment/prod
  - zenvara/postgresql
  - zenvara/sftp

output:
  archived: !int

steps:
  - $rows:
      invoke: postgresql.query
      on: audit
      with: { Query: "SELECT * FROM incidents WHERE archived = false" }

  - $upload:
      create: sftp.file
      on: drop
      with:
        Path: "/incidents/${= str(_run-id)}.json"
        Input: "${= toJson(rows.rows)}"

  - return:
      archived: "${= len(rows.rows)}"

Run it twice:

zen run-flow incident-archive --env dev
zen run-flow incident-archive --env prod

Same flow, different audit DB, different SFTP drop zone. The environment is the only thing that changed — which is the whole point of the model.

When the definition itself changes

This example is the run loop: one finished flow, swapped between environments at run time. The moment you need to edit the flow — or the connections, or the environments — and ship the new version safely, you are in the change loop, and that runs on a different axis: you stage the edit on a branch, review the diff, and promote. Environments answer which systems; branches answer which version. From Dev to Prod walks both loops end to end, and Environments vs Branches explains why they never collide.