Curiosity - Configuration Sync (Git)

Configuration Sync to Git

The Workspace can mirror its administrative configuration — schemas, roles, permissions, connectors, scheduled tasks and other definitions — into a Git repository. Every change made by an admin is committed automatically, with the author and an optional message attached. When a remote is configured, the same commits are pushed upstream so the repository becomes the audit trail and the disaster-recovery copy of the workspace configuration.

Use it to:

Track who changed which configuration setting, and when.
Promote configuration from staging to production by pulling the same commits into another workspace.
Recover a known-good configuration after a misconfiguration or a restore.

Scope

Only administrative configuration (the "definitions" exported by the workspace) is tracked. Graph content, ingested documents, embeddings and search indexes are not stored in this repository — those belong to backups. See Backup and restore.

How it works

On startup, when MSK_GIT_TRACK_STATE_PATH is set, the workspace opens (or initializes) a Git repository at that path and checks out the configured branch. From then on, every tracked administrative change triggers an export of the current configuration into the repository's definitions/ folder, followed by a commit with the author set to the user who made the change.

If MSK_GIT_REMOTE_URL is also set, the workspace pushes the branch upstream after each commit using the supplied credentials.

Required environment variables

Variable	Required	Default	Description
`MSK_GIT_TRACK_STATE_PATH`	yes	—	Absolute path to the local directory used as the Git working tree. Created and `git init`-ed on first start if it doesn't already contain a `.git` folder.
`MSK_GIT_TRACK_STATE_BRANCH`	no	`main`	Branch that receives the configuration commits.
`MSK_GIT_REMOTE_URL`	no	—	HTTPS URL of the remote repository to push commits to. When unset, history stays local.
`MSK_GIT_REMOTE_USERNAME`	conditional	—	Username for the remote. Required when `MSK_GIT_REMOTE_URL` is set and the remote requires authentication.
`MSK_GIT_REMOTE_PASSWORD`	conditional	—	Password or personal access token for the remote. Required alongside `MSK_GIT_REMOTE_USERNAME`.

Persist the repository path

MSK_GIT_TRACK_STATE_PATH must point to a location that survives container restarts. In Docker or Kubernetes, mount a volume at that path — otherwise the repository is recreated on every start and the history is lost.

Credentials

Use a service account or a personal access token scoped to the single configuration repository — not a long-lived user credential.

GitHub: a fine-grained PAT with Contents: read & write on the target repository works as the password. Set MSK_GIT_REMOTE_USERNAME to any non-empty string (GitHub ignores it for PAT auth).
GitLab: a project access token with the Developer role and the write_repository scope.
Azure DevOps: a PAT with Code: Read & Write. Use the PAT as the password.

What ends up in the repository

The first commit on a fresh repository contains only a README.md placeholder. Subsequent commits add and update files under definitions/. The full layout is regenerated from the live workspace on every change, so the working tree always reflects the workspace's current configuration — there are no partial edits.

Each commit message follows the pattern:

Configuration Sync (<optional context provided by the change>)

The author is the user who triggered the change (full name and email taken from their workspace profile). The committer is always the Curiosity Workspace service identity.

Do not commit manually

The repository is regenerated by the workspace on every tracked change. Manual commits or edits to the working tree will be overwritten the next time an admin changes configuration. Treat the repository as read-only on the remote side and use it for review and audit only.

Troubleshooting

Symptom	Likely cause	Fix
Repository is recreated on every restart	`MSK_GIT_TRACK_STATE_PATH` points to a non-persistent location (e.g. inside the container's writable layer).	Mount a volume at that path.
Commits land locally but are never pushed	`MSK_GIT_REMOTE_URL` is unset, or credentials are wrong.	Set the remote URL and verify the username/password against the provider's auth requirements.
`repository path not owned by current user` in the logs	Mounted volume is owned by a different UID inside the container.	The workspace already disables LibGit2's owner validation; if you still see this, check filesystem permissions on the mount.
Commits appear with no author name	The user who made the change has no profile name or email set.	Update the user's profile in the workspace; future commits use the new identity.