GitOps configuration sync
Keep Prelude Collector configuration in a Git repository with bidirectional sync — export to a tagged commit and import Git-side edits through a previewed reconcile.
Prelude Collector can keep its configuration in a Git repository, with changes flowing both ways. Push the live configuration to a Git remote as a versioned, tagged commit, and pull Git-side edits back through a previewed reconcile. This gives you review, history, and rollback for your collector setup using the tools your team already runs.
What is tracked:
- Devices and their protocols
- Data models
- Subscriptions
- Transforms
- Output backends
Git is the source of truth on import. An import is a full reconcile: objects added in Git are created, changed objects are updated, and objects removed from Git are deleted. Always review the preview before applying.
Secrets are never written to Git
Sensitive values — device credentials and output backend secrets — are redacted on export and never leave the collector. On import they are preserved: a blank secret means "keep the existing value", so a round-trip through Git never wipes or exposes a credential.
Prerequisites
- A Git repository you can reach over HTTPS (GitLab or GitHub both work).
- A personal access / project token with write access to that repository.
The token is stored encrypted at rest and is used only for the duration of
a push/fetch — it is never written into the repository's
.git/config.
Configure the connection
In the web UI, open Settings → Git Sync and provide:
| Setting | Description |
|---|---|
| Repository URL | The HTTPS clone URL of the config repository. |
| Token | A write-capable access token (encrypted at rest). |
| Branch | The branch to push to and fetch from. |
| Format | JSON or YAML for the serialized configuration. |
Push configuration to Git
From Settings → Git Sync, choose Push to Git. The collector serializes the tracked objects, redacts secrets, and creates a tagged commit on the configured branch. The tag gives you a stable reference for each exported state.
Pull and apply Git-side edits
- Preview — choose Pull to fetch the repository and compute a diff against the live configuration. The preview lists exactly what will be created, updated, and deleted.
- Apply — once the diff looks right, Apply runs the full reconcile through the collector's normal create/update/delete paths and live-engine reconcile, so device activation, subscription reconcile, output reload, and the model registry all pick up the change without a restart.
Devices and subscriptions are matched by hostname, so the same logical device reconciles cleanly even if its management address changes.
REST API
The same operations are available over the REST API:
| Method & path | Purpose |
|---|---|
GET /api/v1/config/git-settings |
Read the current Git Sync settings. |
PUT /api/v1/config/git-settings |
Update the Git Sync settings. |
POST /api/v1/config/export |
Push the live configuration to Git. |
POST /api/v1/config/import |
Fetch and preview the reconcile diff. |
POST /api/v1/config/import/apply |
Apply the previewed reconcile. |
See the API reference for request and response details.