Skip to main content

Configuration Version History: Compare, Diff, and Rollback

Keeptrusts handles configuration version history on /configurations/entity/{configId}: you compare saved versions, inspect semantic summaries and exact YAML, then roll back by restoring an earlier saved version into the editor and deploying it as a new controlled version rather than relying on an opaque one-click revert.

Use this page when​

  • You need to see exactly what changed between two policy versions.
  • You want a safe rollback path after a bad rollout.
  • You need a version history that is useful for both engineering and audit review.

Primary audience​

  • Primary: Technical Engineers responsible for policy rollout
  • Secondary: Technical Leaders and reviewers who need a defensible change record

The problem​

Version history is only useful if it answers three questions quickly:

  • what changed
  • why it changed
  • how to get back to a known-good state

Many systems fail one or more of those questions. They keep a timestamp and maybe a version label, but not enough context to support actual operations. In practice that means engineers still have to reconstruct intent from memory, chat logs, or local files.

That is especially dangerous with policy configuration. A single change can alter verdict mix, escalations, provider routing, cost, or redaction behavior. When an incident happens, "something changed" is not enough. You need the exact version pair, the related gateway deployment state, and a controlled path to restore the previous behavior.

The current Keeptrusts product supports that workflow, but it helps to use the right page for the right job.

The solution​

Think of the configuration surfaces as a three-step stack.

/configurations is the searchable inventory. That is where you locate the right managed record by name, version, gateway, or change detail.

/configurations/entity/{configId} is the history and comparison page. It shows saved versions, source, change detail, SHA-256, saved timestamp, YAML preview, and deployment status across gateways. This is the page for understanding history.

/configurations/{configId} is the editor and deployment-review page. This is where you save a new version, inspect the review summary, toggle raw YAML diff, and deploy.

That split matters because rollback is a controlled authoring action in the current console, not a hidden mutation against history. If you need to restore an earlier known-good state, you copy or reopen the earlier saved YAML, load it into the editor, review the difference against the latest state, save a new version with an explicit reason, and then deploy it. Operationally, that is safer than mutating history in place.

Implementation​

Use this workflow whenever you are investigating a suspected regression or planning a restore.

  1. Open /configurations and select the affected configuration.
  2. Move to /configurations/entity/{configId} to inspect the version table and deployment state.
  3. If there are at least two saved versions, use the compare panel to choose a baseline and target version.
  4. Read the semantic change summary first. It is faster and usually more useful than jumping directly into raw YAML.
  5. If you need exact line-level confirmation, view the YAML previews or return to the editor route and use the raw diff panel there.

The detail page is particularly useful because it combines history and runtime context. You are not looking at version labels in isolation. You can also see where the configuration is currently deployed and whether gateway deployment status matches your expectation.

A practical rollback workflow looks like this:

  1. Identify the last known-good saved version on /configurations/entity/{configId}.
  2. Open that version's YAML preview and copy the content.
  3. Open /configurations/{configId}.
  4. Paste the prior YAML into the editor.
  5. Review the semantic summary and, if needed, the raw YAML diff against the latest saved state.
  6. Save a new version with a change detail such as Restore pre-rollout baseline after escalation spike.
  7. Deploy the restored version to the affected gateways.
  8. Confirm the deployment and recheck /events and /escalations for the relevant time window.

If you want an explicit command-line check before you save the restore version, the same local lint step still helps:

kt policy lint --file policy-config.yaml

That is useful when the rollback involves more than a pure restore, such as reverting one part of a change while keeping another.

There is another operational benefit to the history page that is easy to overlook: supplemental operator notes. If the target version has a meaningful changeDetail, that note is shown alongside the comparison context. In practice that is often the fastest way to understand whether a change was a planned rollout, an emergency mitigation, or a maintenance cleanup.

Two habits improve the value of version history substantially.

The first is to write real change details at save time. "Fix config" is barely useful. "Reduce reviewer noise for support macros" is useful.

The second is to treat rollback as a new controlled release. That preserves a truthful history. Instead of pretending the bad version never existed, you create a visible, auditable restoration event.

Results and impact​

Used well, the version-history workflow shortens incident analysis and improves ordinary change review. Engineers can compare real versions instead of diffing stray files. Reviewers can see whether the gateway fleet actually reflects the intended state. Leaders can explain not only that a rollback happened, but also why and when it was executed.

It also makes rollback safer. Restoring a prior YAML state as a new saved version keeps the audit trail intact and forces one more review step before deployment. That extra discipline is usually worth it because policy rollback affects live governance behavior, not just internal code.

Key takeaways​

  • Use /configurations/entity/{configId} for version history and comparison, not the editor route.
  • Read semantic comparison first, then inspect exact YAML only when needed.
  • In the current console, rollback is best handled by restoring earlier YAML into a new saved version and deploying it.
  • Deployment status belongs in the rollback conversation; history without runtime state is incomplete.
  • Good change details make version history much more useful during incidents.

Next steps​