Docs
GitOps
Export, plan, and apply stack desired-state as nixploy.yaml.
Flow
- Export a project/environment stack to nixploy.yaml
- Edit or store it in Git
- plan — see create/update/delete diffs without applying
- apply — converge the live stack and redeploy the services that actually changed
- syncFromUrl / syncFromGit — pull desired state into the panel
Available in the project GitOps UI and via the nixploy gitops export / plan / apply / sync-url CLI commands.
What the file covers (version 2)
Every service row and everything attached to it: source and build settings, resources, deploy hooks, Swarm overrides, preview settings, domains with their middleware chains, mounts, published ports, redirects and basic auth. Rows a service references by id — the pull and push registry, the server it is pinned to — are written by name, so the same file applies on another instance.
1version: 2
2project: { name: shop }
3environment: { name: production }
4applications:
5 - name: api
6 environment: production
7 sourceType: github
8 repository: acme/api
9 branch: main
10 buildType: dockerfile
11 replicas: 2
12 pushRegistry: ghcr
13 hooks: { preDeploy: npm run migrate }
14 previews: { enabled: true, limit: 3 }
15 domains:
16 - host: api.acme.dev
17 https: true
18 certificateType: letsencrypt
19 middlewares:
20 - kind: rateLimit
21 config: { average: 100, burst: 200 }
22 mounts:
23 - { type: volume, mountPath: /var/lib/api, volumeName: api-3f9a1c-data }
24 ports:
25 - { published: 9100, target: 9100 }
26 basicAuth:
27 - { username: metrics, password: change-me }- An omitted scalar means leave as is, never reset — a file that lists only repository and branch changes only those two columns.
- An array (domains, mounts, ports, redirects, basicAuth, a domain's middlewares) is the whole desired set: rows it lists are created or patched, rows it leaves out are deleted, [] removes every row, and an omitted array leaves the rows alone.
- Values never enter the file: env is key names only, basic-auth passwords are write-only, and hook commands, inline compose files and file-mount contents are exported only to a caller with secrets.read.
- A version 1 file is still accepted and upgraded on read; export always writes version 2.
- The values travel separately: nixploy gitops export-secrets seals the env of the project, the environment and every service by name with a passphrase, and nixploy apply --secrets writes them after the manifest and before the redeploy.
What apply checks
Apply goes through the same checks as the panel forms: service.create and the quota for every new service, service.write for updates, service.deploy for the redeploy (skip it with redeploy: false), secrets.write when the file carries hooks, passwords or file contents, and the instance admin for bind mounts, Swarm network or privilege overrides and publishing compose ports. Mount paths, redirect rules, middleware configs and forward-auth targets are validated exactly as their routers validate them.
Apply is deliberately not one big transaction: every service is applied independently, so one item that fails is reported with its reason while the rest of the stack is still written. A service's domains and middleware chains are reconciled in one transaction, then Traefik is rewritten once. Items that failed to apply are never redeployed, and databases are skipped for redeploy because they have no build. The full reference is docs/gitops.md in the repository.
Also see the repository guides under docs/ · REST API reference