Skip to content

GitOps Definitions

GitOps definitions turn your tenant’s automation into code: your actions, flows, sources, and sinks live as YAML files in a git repository you own (GitHub, Bitbucket, or Azure DevOps), and Nexomatic reconciles the tenant from that repo on every commit. The repo is the source of truth — edits flow repo → platform, and a manual export mirrors the platform back to the repo.

The platform’s part is two endpoints: export and import. The GitOps machinery itself — the import/export flow pair, their actions, source, and sink — is ordinary definitions, shipped as a bundle you import like any other.

Two flows do the transport:

git push ──► provider webhook ──► gitops-import flow (auto)
GitPull ──► GitOpsImport
manual fire ──► gitops-export flow (on demand)
GitOpsExport ──► GitCommitPush (skipped when nothing changed)

Every import is a full apply: resources are upserted by name with repo values winning; anything absent from the repo is left alone (deletion only happens with an explicit prune). Secrets never leave the platform — YAML carries secret key references, and the git token itself lives in the tenant secret store.

The four transport modules are documented in Nexo GitOps and Nexo Platform; the bundle’s field-by-field format is the GitOps YAML reference.

Three steps: create the PAT secret, import the bundle, register the webhook.

1. Create the git token as a tenant secret. Open Secrets and create a secret with key nexomatic-gitops-pat holding your provider PAT / app password — or through the API:

Terminal window
curl -X POST https://<your-platform>/api/v1/secret \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{"key": "nexomatic-gitops-pat", "value": "<your-provider-PAT>"}'

2. Import the GitOps bundle. The platform ships the machinery as YAML definitions (docs/gitops-bundle/ in the platform repository): the gitops-import-webhook source, gitops-runner sink, the four actions (gitops-pull, gitops-import, gitops-export, gitops-push), and the gitops-import / gitops-export flows. The simplest path: copy those files into your definitions repo — your first commit applies them like any other bundle. To import them directly instead, post them as the import body:

Terminal window
curl -X POST https://<your-platform>/api/v1/gitops/import \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
--data-binary @<(python3 -c 'import json,os
root="docs/gitops-bundle"
print(json.dumps({"files":{os.path.relpath(os.path.join(d,f),root).replace(os.sep,"/"):open(os.path.join(d,f)).read() for d,_,fs in os.walk(root) for f in fs if f.endswith(".yaml")}}))')

After importing, edit the two placeholders in the actions: set repo (and branch) on gitops-pull and gitops-push to your repo’s clone URL, and set api_url on gitops-import and gitops-export to your platform’s address (e.g. https://automatics.example.com). For Bitbucket and Azure DevOps also fill username (your account username / any value respectively; leave empty for GitHub). Re-import after editing.

3. Register the commit webhook. Open the gitops-import flow in the editor to see its webhook address, then register it in your provider:

ProviderWhereWhat to paste
GitHubSettings → Webhooks → Add webhookPayload URL = the flow’s webhook address, content type application/json, event = Just the push event
BitbucketRepository settings → Webhooks → Add webhookURL = the flow’s webhook address, trigger = Push
Azure DevOpsProject settings → Service hooks → Web hooksURL = the flow’s webhook address, trigger = Code pushed

Any push triggers a full apply — the webhook payload’s contents are not interpreted, and the actual fetch is authenticated with your PAT. If your provider cannot send the platform’s signature headers, disable signature verification on the webhook: a forged webhook can at worst trigger a redundant pull, because only the repo’s own contents are ever applied.

actions/ fetch-invoice.yaml kind: Action
flows/ invoice-sync.yaml kind: Flow
sources/ webhook-listener.yaml kind: Source
sinks/ accounting-server.yaml kind: Sink

Resources are identified by name (unique per tenant); everything cross-references by name — a flow names its sources, sink, and actions. Node pins are by node name and fall back gracefully at import time: a source pinned to a missing node lands on platform placement, a sink on the pool — each with a note in the import report. (At runtime the rule is the opposite: a pinned node that goes offline never falls back to the platform — its work is held until the node returns.) No node identity ever lives in the repo; nodes remain hand-created infrastructure.

flows/invoice-sync.yaml
kind: Flow
name: invoice-sync
enabled: true
sources:
- webhook-listener
- nightly-schedule
sink: accounting-server
entry_action: fetch-invoice
queue: { supersede_queued: false, ttl_seconds: null }
chain:
- { from: fetch-invoice, on: success, to: parse-invoice, order: 0, placement: any, sink: null }
triggers:
- { type: schedule, enabled: true, config: { crontab: "0 9 * * *" } }

A flow’s sources list holds its trigger sources — one per source type; each fires the flow independently (the webhook address above and the schedule cron). An empty list makes a manual-only flow, fired from the flows grid’s run-now.

Actions reference library modules as library/module (for example nexo-shell/Shell or nexo-gitops/GitPull); secrets in params use type: SECRET with the tenant secret key as the value — the real secret is resolved at runtime and never appears in git.

Fire the gitops-export flow manually (the flow’s run-now action in the grid, or POST /api/v1/eventtype/<uuid>/fire with {"test": false, "params": {}}). It exports the tenant’s current definitions, commits, and pushes — and skips the commit and push entirely when nothing changed. The import flow’s event log shows the per-object report of every import (created / updated / unchanged / failed with a reason).

By default an import never deletes anything: resources not in the repo are reported as kept (not in the bundle). To make the repo the complete definition of the tenant, pass the prune flag on the import call:

Terminal window
curl -X POST https://<your-platform>/api/v1/gitops/import \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{"files": {...}, "prune": true}'

A pruning import still refuses to delete a source, sink, or action that a surviving flow references — those are reported as kept (referenced by a flow).

  • The sink node running the flows must be tenant-pinned — the flows’ API calls authenticate as the executing node’s identity, and the token exchange yields the tenant from the node’s pin. Hand-created nodes pin the tenant at creation; the import/export actions carry no credentials of their own.
  • The executing node needs git installed — GitPull fails loudly and names git when it is absent.
  • The two platform libraries (nexo-gitops, nexo-platform) ship with the platform; importing the bundle fails with a clear error if they are not seeded.
  • Import and export calls are authorized like any other tenant endpoint: your roles through the UI, the node’s identity when a flow action runs.