Skip to content
Documentation Prelude Collector

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

  1. 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.
  2. 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.

Filtering by: