Mirror config history to a Git repository

LinkMesh keeps every configuration change in its own Git history. You can connect an external Git repository (GitLab, GitHub, Gitea, …) under Settings → GitOps to get a copy of that history where your team already reviews code, backs up, and audits.

That repository is a read-only mirror. LinkMesh writes to it; it never reads configuration back from it.

What reaches the mirror

LinkMesh pushes every version it records, as soon as it records it:

• every save — each one is its own version;
• the versions LinkMesh records on its own, such as a new collector’s default configuration;
• the version a rollback creates in Version History.

A fleet re-push creates no version, but it pushes again if the mirror had fallen behind. The commit, publish and rollback API responses carry a mirror object that says whether the push was accepted:

"mirror": {
  "inSync": false,
  "outOfSyncSince": "2026-09-30T08:00:00Z",
  "reason": "diverged",
  "error": "non-fast-forward update: refs/heads/main"
}

The object is absent on a server with no repository connected.

Edits in the repository are not applied

Changing the repository does not change collectors

Collectors always run LinkMesh’s own configuration. A commit pushed straight to the mirror, a merge request merged there, or a webhook from your Git host never reaches a collector. Make configuration changes in LinkMesh, through the UI or the API.

A call to POST /api/v1/settings/git/webhook (from your Git host or a CI job, authenticated like any other API call) makes LinkMesh push its history again right away, so a repository that someone else has written to is flagged as out of sync immediately rather than at the next change.

When the mirror is out of sync

A push fails when the repository has commits LinkMesh does not have (someone pushed to it directly), or for any other reason: an expired token, a protected branch, a network error. LinkMesh never merges the repository’s commits into the live configuration to make the push succeed. Instead:

• Settings → GitOps and Version History show Remote mirror out of sync since <time>, with the error, until a push succeeds again;
• the audit log records the moment it went out of sync, and the moment it came back;
• the response of the action that triggered the push carries the state.

Your change is live either way. Only the mirror is behind.

Recover a diverged mirror

1. Decide what to do with the repository-only commits. They were never applied to collectors. If any of them contain a change you want, make the same change in LinkMesh first, so it becomes part of LinkMesh’s history.

2. Overwrite the repository with LinkMesh’s history. On Settings → GitOps, click Overwrite remote with LinkMesh history, or call the API:

   curl -X POST "$LINKMESH/api/v1/settings/git/mirror/force-push" \
     -H "Authorization: Bearer $TOKEN"

   This force-pushes LinkMesh’s branch to the repository. Commits that exist only on the repository are removed from it.

3. Check the banner is gone. A successful push clears the out-of-sync state and adds an audit entry.

If the push failed for another reason (reason: push_failed), fix the cause — typically the token or branch protection under Settings → GitOps — and push again with the same button, or simply make your next change.

Tip

Protect the mirror branch in your Git host so that only LinkMesh’s token can push to it (and may force-push, for the recovery above). A mirror nobody else can write to cannot diverge.