Skip to content

GitOps YAML Reference

This reference describes the bundle format exchanged by the platform’s import/export endpoints and by the GitOpsExport / GitOpsImport library modules. For how the bundle moves, see GitOps Definitions; for the transport modules, Nexo GitOps and Nexo Platform.

A bundle is a map of file path → YAML text, each file holding exactly one resource. The endpoints carry it as JSON — export returns {"files": {"actions/foo.yaml": "kind: Action\n…"}} and import takes the same shape.

Exported bundles use this layout:

actions/ <action-name>.yaml
flows/ <flow-name>.yaml
sources/ <source-name>.yaml
sinks/ <sink-name>.yaml

Import walks every *.yaml file regardless of path, so a hand-written repo may organize differently; the four directories are the export’s convention.

Serialization is canonical (sorted keys, block style), so export → import → export is byte-stable. Hand-written files need not be sorted — anything that parses as YAML works.

Filenames — unsafe characters (anything outside letters, digits, ., _, -) collapse to -; when that changes the name, a short hash suffix (-ab12) keeps distinct names on distinct files.

  • Every resource has kind — one of Action, Flow, Source, Sink — and a non-empty name, unique per tenant within its kind.
  • Everything cross-references by name: a flow names its source, sink, and actions.
  • Fields marked default apply when the key is missing; unknown fields are ignored.
  • SECRET parameter values are secret keys — the actual secret values never leave the platform and never appear in an export.
kind: Source
name: gitops-import-webhook
type: SOURCE:WEBHOOK
placement: platform
node: null
config: null
FieldRequiredMeaning
nameyesUnique per tenant
typeyesThe preset name (for example SOURCE:WEBHOOK, SOURCE:MQTT, SOURCE:SCHEDULER) — must exist and be accessible to the tenant, or the import fails
placementdefault platformplatform or pinned
nodefor pinnedNode name — a pinned source whose node is missing falls back to platform placement with a note in the report
confignoThe preset’s connection config as a map; secret values reference the tenant’s store as secret://…/<key> and the key must exist
kind: Sink
name: gitops-runner
placement: null
node: null
constraints: []
FieldRequiredMeaning
nameyesUnique per tenant
placementnopinned or null (the pool — any matching node)
nodefor pinnedNode name — a pinned sink whose node is missing falls back to the pool with a note in the report
constraintsnoPlacement constraints as "attribute:value" strings; unknown attributes or values are skipped with a note in the report
kind: Action
name: gitops-pull
enabled: true
module: nexo-gitops/GitPull
params:
- key: repo
order: 2
type: STATIC
value: https://github.com/your-org/your-definitions
- key: token
order: 6
type: SECRET
value: nexomatic-gitops-pat
FieldRequiredMeaning
nameyesUnique per tenant
enableddefault trueWhether the action can run
moduleyeslibrary/module — for example nexo-gitops/GitPull or nexo-shell/Shell; resolves to the newest accessible version of that library carrying the module, and the import fails if either is missing
paramsnoOrdered list of {key, order, type, value} — type is STATIC, DATA, or SECRET; a SECRET value is the tenant secret key and must exist
kind: Flow
name: gitops-import
description: 'GitOps import: any push webhook applies the repo''s bundle'
enabled: true
placement: any
sources:
- gitops-import-webhook
sink: gitops-runner
entry_action: gitops-pull
queue:
supersede_queued: false
ttl_seconds: null
chain:
- from: gitops-pull
on: success
to: gitops-import
order: 0
placement: any
sink: null
triggers: []
FieldRequiredMeaning
nameyesThe flow’s display name, unique per tenant
descriptionno
enableddefault true
placementdefault anyThe placement string (any for any matching node, platform) — the effective execution target is the named sink
sourcesnoThe flow’s trigger sources by name — each must exist, or the import fails. One source per type per flow (two sources of the same type is rejected). Empty ([]) = a manual-only flow, fired from the flows grid’s run-now
sinknoSink name
entry_actionnoAction name — must exist, or the import fails
queuenosupersede_queued (default false) — drop a queued event when a newer one arrives; ttl_seconds (number or null) — queue time-to-live
chainnoOrdered links {from, on, to, order, placement, sink} — from/to are action names (must exist), on is success (default) or failure, placement defaults to any, sink names an optional per-step sink
triggersnoList of {type, enabled, config} — enabled defaults to true; the type must be registered and the config is validated like the flow builder
TypeConfig fields
schedulecrontab (required) — cron expression firing the flow; event_data (JSON string payload); data_version; sink_id (optional specific sink)
file_watchpaths (required, list) — directories/files to watch; recursive (default true); include_hidden (default false)
mqtttopics (required, list); qos (0, 1 or 2, default 0)
self_webhooknone — the listener serves the flow’s own address

A flow on a SCHEDULER source that declares no schedule trigger gets one added at import, taken from the source’s crontab (the same behavior as the flow builder).

Every import is a full apply:

  • Kinds apply in dependency order — sources, sinks, actions, flows — so flows always find their referenced resources.
  • Upsert by name: a resource matching an existing name is updated with the repo’s values; otherwise it is created. Unchanged resources are reported as such.
  • Each object applies in its own transaction — one bad object is reported failed (with a reason) and the rest of the bundle still lands.
  • The report lists every object: file, kind, name, outcome, reason (on failure), and notes (non-fatal adjustments, such as a pin falling back to platform placement).

Outcomes:

OutcomeMeaning
createdThe resource did not exist and was created
updatedThe repo’s values differ and were applied
unchangedAlready identical to the repo
failedThe object could not be applied — the reason names the cause (unknown preset, missing library or module, unknown reference, unknown trigger, …)
keptPresent in the tenant but not in the bundle
deletedPruned — absent from the bundle and not referenced by a surviving flow

Pruning — by default an import never deletes anything; resources absent from the repo are reported kept (not in the bundle). With prune: true on the API call (the library modules import without pruning), absent resources are deleted — but never a source, sink, or action that a surviving flow references (those stay kept), and a pruned sink is taken offline rather than deleted, keeping its event history.

  • Secret values — only the keys (SECRET params, secret:// config references)
  • Unnamed rows — machine registrations awaiting configuration
  • Nodes, presets, and events — runtime state, never definitions
EndpointBodyReturns
GET /api/v1/gitops/export—{"files": {path → YAML}}
POST /api/v1/gitops/import{"files": {path → YAML}, "prune": false}{"report": [per-object entries]}

Both are ordinary tenant endpoints: your roles authorize UI calls, and the executing node’s identity authorizes flow-action calls (the standard client-credentials exchange — no special tokens).