Documentation / Administration

Version Control

Every pipeline, report, Site, and skill in Nexus carries full git-backed commit history, side-by-side diffs, and one-click restore — durable in your own Azure tenant, multi-replica-safe on writes, and lock-free on reads.

Nexus versions every authored definition the way developers version code. Each pipeline, report, Site, and skill carries a complete commit history, so administrators and authors can see who changed what, compare any two revisions, and roll back to a known-good version without leaving the platform. This page is for administrators and authors who need an audit trail and safe change management for the assets they build.

What gets versioned

Nexus treats every "definition as text" entity as versioned content:

Entity kind	What's stored	Format
Pipeline	The pipeline module	Python source
Report	The report definition	JSON
Site	Page and asset files	HTML / JS / CSS text
Skill	An agent playbook	Markdown

Every save creates a new revision automatically — there is no separate "commit" step to remember, and a no-op save records nothing so history stays clean. Binary assets (images, large uploads) live in object storage and are referenced, not versioned as text. Secrets are never versioned: pipelines, reports, and Sites reference secret names that resolve from Azure Key Vault at run time, so nothing sensitive is ever written into history (see Secrets Management).

The storage substrate

Version history is a real per-tenant git repository, kept as a bare repo on your subscription's Azure Files share. Two design points matter to a reviewer:

It lives in your tenant. The repository, every commit, and every revision are durable state on infrastructure you own. No definition, diff, or revision ever leaves your Azure environment.
The live view is a projection. The queryable, running version of each entity is projected from the repository's HEAD. Restoring or editing re-projects the live view so a change takes effect immediately, while the git history remains the source of truth.

Multi-replica-safe writes, lock-free reads

Nexus can run several server replicas at once, and they share one repository on the file share. Concurrency is handled so replicas never corrupt history:

Writes take a cross-process advisory lock. A commit (save, delete, or restore) acquires an advisory lock before touching the repo, so two replicas committing at the same instant serialize cleanly instead of racing on the same refs. One atomic save is one commit point.
Reads are lock-free. History, get, diff, and status never take the write lock, so reading history or diffing revisions never contends with — or is blocked by — an in-flight save. Read traffic scales across replicas without coordination.

This is why history stays consistent under load and why an author browsing revisions never stalls another author's save.

One surface for every entity

All versioned entities share the same set of verbs, whether you work from the desktop app or the Nexus MCP tools. The same operations apply uniformly across kinds:

List — find entities of a given kind.
Get — read the live (HEAD) version, or any past revision by reference.
Save — create or update; validates and auto-versions in one atomic commit.
Delete — remove an entity (recorded as a deletion in history).
Validate — check a definition without saving it.
History — the commit log, newest first.
Diff — a unified text diff between any two revisions.
Restore — return an entity to an earlier revision.
Status — repository HEAD plus per-kind revision counts.

Because the verbs are identical across kinds, you learn the workflow once and apply it everywhere.

History, diffs, and restore

See who changed what

History returns commits newest-first, each carrying the author, message, timestamp, and parent revision — a complete, queryable audit trail of every change to a definition over its lifetime.

Compare any two revisions

Diff produces a unified text diff between two references — for example the current version against last week's release — so a reviewer can read exactly what moved before approving or restoring.

Roll back in one step

Restore returns an entity to a chosen earlier revision. The restore is itself recorded as a new commit (history is never rewritten) and the live version is re-projected so the change takes effect immediately.

# Available from the desktop app or the Nexus MCP tools

uql_history(kind="report", id="quarterly-revenue")
  -> [ {sha: 9f2c1a, author: "ana@contoso", message: "add region filter", ...},
       {sha: 4b7e08, author: "sam@contoso", message: "initial",            ...} ]

uql_diff(kind="report", id="quarterly-revenue", ref_a="4b7e08", ref_b="9f2c1a")
  -> unified diff (4b7e08 -> 9f2c1a)

uql_restore(kind="report", id="quarterly-revenue", ref="4b7e08")
  -> { committed: true, sha: c10d33, projected: true }

For a Site, address the specific file you want with its sub-path (for example index.html); the same history, diff, and restore verbs apply per file.

Permissions and safety

Version control respects the same role-based access control as the rest of Nexus (see Roles & Permissions):

Reading history and diffs requires the read permission for that kind, and is included in the read-only Reader role.
Restore is a write-level administrative action. It is reserved for admins and rejected for application tokens, because a restore changes live behavior. Automation cannot silently roll a definition back.
Restoring a pipeline rewrites executable source, so it carries the same admin gate as editing a pipeline directly — and if the pipeline carries an execution role, the edit-lock applies. Version control is never a path around your normal change controls.
Path and identifier safety are enforced on every file reference and entity id, so revisions can only be read and written within your own tenant's repository.

Limits & guarantees

History is append-only. Restores add commits; nothing rewrites or deletes past history.
No secrets in history. Only references are stored; credential values never enter the repo.
Durable and private. The repository is Azure Files state in your subscription — it never leaves your tenant.
Concurrent-safe. Writes serialize under an advisory lock; reads never block.

Where to use it

Drive version control from the desktop app, which surfaces history, diffs, and restore directly in the authoring views, or from the Nexus MCP tools for scripted and agent-driven workflows. Both go through the same versioning layer, so a change made one way is immediately visible from the other.