Skip to main content

Multi-Environment Configs: Dev, Staging, and Production Separation

Keeptrusts separates development, staging, and production by treating environment rollout as a configuration and gateway management problem: keep distinct managed configurations or clearly separated saved versions, deploy them to the right gateways from /configurations, and verify the result in runtime pages like /events and /gateways before you promote the same policy behavior to the next environment.

Use this page when​

  • You need a practical way to keep dev, staging, and production policies from drifting into each other.
  • You want to test a policy change safely before it reaches live traffic.
  • You need a clear answer to which environment is currently running which configuration version.

Primary audience​

  • Primary: Technical Engineers and Platform Operators
  • Secondary: Technical Leaders responsible for release discipline

The problem​

Environment separation breaks down quietly. A team starts with one policy-config.yaml, then duplicates it ad hoc, makes a staging-only tweak under time pressure, and a week later nobody can say whether production still matches the approved baseline.

That is especially risky in AI governance because environment drift is not just a deployment hygiene issue. It changes real behavior. One environment may escalate more aggressively. Another may redact differently. A third may still be using an older routing or audit rule. If you cannot map configuration version to runtime environment, you cannot explain why one environment behaved differently from another.

The usual failure modes are familiar:

  • Staging carries experimental policy changes longer than intended.
  • Production inherits a test-only rule because the same YAML was reused without a controlled version step.
  • Teams know a version number changed, but not which gateways actually received it.
  • A regression appears in production and rollback takes longer because nobody knows which saved version was the last stable one.

Keeptrusts helps here, but only if you use the current product boundaries correctly. There is no magic environment object that automatically manages promotion for you. The separation comes from how you structure configurations, versions, gateway targets, and verification.

The solution​

The safest pattern is to make environment intent explicit in the managed configuration workflow.

For most teams, that means one of two approaches.

The first is separate configuration entities, such as support-dev, support-staging, and support-prod. This is the simplest model when each environment legitimately differs in policy scope, retention, or testing rules.

The second is one shared logical configuration with tightly controlled saved versions that are promoted across distinct gateways only after review. This works when you want near-identical behavior and a clearer promotion chain.

Either way, the operational center stays the same:

  • /configurations is the inventory and search surface.
  • /configurations/entity/{configId} is the version-history and comparison surface.
  • /configurations/{configId} is the editing and deploy-review surface.
  • /gateways and /events are where you confirm the runtime actually matches the intended environment.

The important shift is mental, not cosmetic. Treat dev, staging, and production as separate governed release states, not just separate files on disk.

Implementation​

The lowest-friction workflow is to standardize naming, versioning, and runtime checks.

  1. Create a clear naming convention in /configurations. For example: support-dev, support-staging, and support-prod, or assistant-platform with explicit promotion notes in change details.
  2. Reserve development for active drafting and linting. Use staging for realistic traffic and reviewer-volume checks. Keep production changes small and intentional.
  3. Save every environment change with a change detail that explains both the policy intent and the target environment.
  4. Before promotion, compare the saved version in /configurations/entity/{configId} and inspect what changed semantically, not just that a save occurred.
  5. Open the editor route /configurations/{configId} only when you are ready to save or deploy.
  6. After every deployment, confirm the target gateways and inspect a short time window in /events.

Even a simple baseline benefits from explicit environment naming:

pack:
  name: support-staging
  version: 2.3.0
  enabled: true
  description: Support staging baseline

policies:
  chain:
    - audit-logger
    - pii-detector

policy:
  audit-logger:
    retention_days: 30
  pii-detector:
    action: redact

That YAML is not doing the separation by itself. The separation comes from how you manage it.

A practical promotion flow looks like this:

  1. Draft or update the development configuration in /configurations/new or the existing editor route.
  2. Save a version and write a specific note such as Stage stricter support redaction before production rollout.
  3. Deploy only to the staging gateways.
  4. Use /events to inspect representative traffic and /escalations to see whether reviewer load changed.
  5. If the result is acceptable, apply the same intended change to the production configuration or restore the same validated YAML into the production entity, save it as a new version, and deploy to production gateways.

This is also where the compare view on /configurations/entity/{configId} becomes valuable. If staging behaved differently than expected, you can compare saved versions directly, inspect the semantic summary, and confirm whether the difference is really the new policy or a separate environment-specific change.

Two habits make this much more reliable.

The first is to avoid hidden environment-specific edits. If production needs a different behavior, encode that intentionally in the production-managed config and note it in the change detail. Do not rely on memory.

The second is to verify runtime, not just saved state. A saved version proves author intent. Runtime pages prove what the gateways actually enforced.

Results and impact​

When environment separation is handled this way, policy releases become easier to reason about. Engineers can explain which version ran in staging, which one reached production, and what changed between them. Reviewers can correlate queue spikes with the exact saved version that introduced them. Leaders can approve promotion based on evidence instead of assumption.

It also shortens incident response. If production starts escalating unexpectedly, you do not need to diff random files from laptops. You can open the configuration detail page, compare saved versions, see recent deployments, and work backward from a known runtime target.

Most importantly, this approach reduces accidental policy drift. Development remains fast, staging remains representative, and production remains defensible. That is what environment separation is supposed to achieve.

Key takeaways​

  • Keeptrusts does not rely on a hidden environment abstraction; separation comes from managed configurations, saved versions, gateway targets, and verification.
  • Use /configurations for inventory, /configurations/entity/{configId} for version comparison, and /configurations/{configId} for editing and deployment review.
  • Write change details that include environment intent, not just the technical change.
  • Promote only after verifying staging behavior in /events, /gateways, and, when relevant, /escalations.
  • Treat saved versions as release states, not just checkpoints.

Next steps​