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.
How it works
Section titled “How it works”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.
Onboarding
Section titled “Onboarding”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:
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:
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,osroot="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:
| Provider | Where | What to paste |
|---|---|---|
| GitHub | Settings → Webhooks → Add webhook | Payload URL = the flow’s webhook address, content type application/json, event = Just the push event |
| Bitbucket | Repository settings → Webhooks → Add webhook | URL = the flow’s webhook address, trigger = Push |
| Azure DevOps | Project settings → Service hooks → Web hooks | URL = 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.
Repo layout
Section titled “Repo layout”actions/ fetch-invoice.yaml kind: Actionflows/ invoice-sync.yaml kind: Flowsources/ webhook-listener.yaml kind: Sourcesinks/ accounting-server.yaml kind: SinkResources 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.
kind: Flowname: invoice-syncenabled: truesources: - webhook-listener - nightly-schedulesink: accounting-serverentry_action: fetch-invoicequeue: { 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.
Running an export
Section titled “Running an export”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).
Pruning
Section titled “Pruning”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:
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).
Requirements and limits
Section titled “Requirements and limits”- 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
gitinstalled — 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.