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.
The bundle
Section titled “The bundle”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>.yamlflows/ <flow-name>.yamlsources/ <source-name>.yamlsinks/ <sink-name>.yamlImport 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.
Common rules
Section titled “Common rules”- Every resource has
kind— one ofAction,Flow,Source,Sink— and a non-emptyname, 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.
SECRETparameter values are secret keys — the actual secret values never leave the platform and never appear in an export.
Source
Section titled “Source”kind: Sourcename: gitops-import-webhooktype: SOURCE:WEBHOOKplacement: platformnode: nullconfig: null| Field | Required | Meaning |
|---|---|---|
name | yes | Unique per tenant |
type | yes | The preset name (for example SOURCE:WEBHOOK, SOURCE:MQTT, SOURCE:SCHEDULER) — must exist and be accessible to the tenant, or the import fails |
placement | default platform | platform or pinned |
node | for pinned | Node name — a pinned source whose node is missing falls back to platform placement with a note in the report |
config | no | The preset’s connection config as a map; secret values reference the tenant’s store as secret://…/<key> and the key must exist |
kind: Sinkname: gitops-runnerplacement: nullnode: nullconstraints: []| Field | Required | Meaning |
|---|---|---|
name | yes | Unique per tenant |
placement | no | pinned or null (the pool — any matching node) |
node | for pinned | Node name — a pinned sink whose node is missing falls back to the pool with a note in the report |
constraints | no | Placement constraints as "attribute:value" strings; unknown attributes or values are skipped with a note in the report |
Action
Section titled “Action”kind: Actionname: gitops-pullenabled: truemodule: nexo-gitops/GitPullparams:- key: repo order: 2 type: STATIC value: https://github.com/your-org/your-definitions- key: token order: 6 type: SECRET value: nexomatic-gitops-pat| Field | Required | Meaning |
|---|---|---|
name | yes | Unique per tenant |
enabled | default true | Whether the action can run |
module | yes | library/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 |
params | no | Ordered list of {key, order, type, value} — type is STATIC, DATA, or SECRET; a SECRET value is the tenant secret key and must exist |
kind: Flowname: gitops-importdescription: 'GitOps import: any push webhook applies the repo''s bundle'enabled: trueplacement: anysources:- gitops-import-webhooksink: gitops-runnerentry_action: gitops-pullqueue: supersede_queued: false ttl_seconds: nullchain:- from: gitops-pull on: success to: gitops-import order: 0 placement: any sink: nulltriggers: []| Field | Required | Meaning |
|---|---|---|
name | yes | The flow’s display name, unique per tenant |
description | no | |
enabled | default true | |
placement | default any | The placement string (any for any matching node, platform) — the effective execution target is the named sink |
sources | no | The 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 |
sink | no | Sink name |
entry_action | no | Action name — must exist, or the import fails |
queue | no | supersede_queued (default false) — drop a queued event when a newer one arrives; ttl_seconds (number or null) — queue time-to-live |
chain | no | Ordered 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 |
triggers | no | List of {type, enabled, config} — enabled defaults to true; the type must be registered and the config is validated like the flow builder |
Trigger configs
Section titled “Trigger configs”| Type | Config fields |
|---|---|
schedule | crontab (required) — cron expression firing the flow; event_data (JSON string payload); data_version; sink_id (optional specific sink) |
file_watch | paths (required, list) — directories/files to watch; recursive (default true); include_hidden (default false) |
mqtt | topics (required, list); qos (0, 1 or 2, default 0) |
self_webhook | none — 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).
Apply semantics
Section titled “Apply semantics”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), andnotes(non-fatal adjustments, such as a pin falling back to platform placement).
Outcomes:
| Outcome | Meaning |
|---|---|
created | The resource did not exist and was created |
updated | The repo’s values differ and were applied |
unchanged | Already identical to the repo |
failed | The object could not be applied — the reason names the cause (unknown preset, missing library or module, unknown reference, unknown trigger, …) |
kept | Present in the tenant but not in the bundle |
deleted | Pruned — 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.
Never exported
Section titled “Never exported”- Secret values — only the keys (
SECRETparams,secret://config references) - Unnamed rows — machine registrations awaiting configuration
- Nodes, presets, and events — runtime state, never definitions
Endpoints
Section titled “Endpoints”| Endpoint | Body | Returns |
|---|---|---|
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).