checkId: check.environment.drift plugin: stellaops.doctor.environment severity: warn tags: [environment, drift, configuration, consistency]

Environment Drift Detection

Doctor check check.environment.drift — for operators and release engineers confirming that configuration stays consistent across environments, so a promotion-based release behaves in production the way it did in staging.

What It Checks

Queries the Release Orchestrator drift report API (/api/v1/environments/drift) and compares configuration snapshots across environments. The check requires at least 2 environments to perform comparison. Each drift item carries a severity classification:

Fail if any drift is classified as critical (e.g., security-relevant configuration differences between staging and production)
Warn if drifts exist but none are critical
Pass if no configuration drift is detected between environments

Evidence includes the specific configuration keys that drifted and which environments are affected.

Why It Matters

Configuration drift between environments undermines the core promise of promotion-based releases: that what you test in staging is what runs in production. Drift can cause subtle behavioral differences that only manifest under production load, making bugs nearly impossible to reproduce. Critical drift in security-related configuration (TLS settings, authentication, network policies) can create compliance violations and security exposures.

Common Causes

Manual configuration changes applied directly to one environment (bypassing the release pipeline)
Failed deployment that left partial configuration in one environment
Configuration sync job that did not propagate to all environments
Environment restored from an outdated backup
Intentional per-environment overrides that were not tracked as accepted exceptions

How to Fix

stella env … does not exist. Verified 2026-07-28 against the built CLI: stella env drift show exits 2 with Unrecognized command or argument 'env'. No env or environment command is registered at any depth, and no alias in src/Cli/StellaOps.Cli/cli-routes.json maps either token. Earlier revisions of this article published stella env drift show and stella env drift accept <config-key> as remediation steps; both were fabricated.
Use instead: the Doctor check itself (stella doctor run --check check.environment.drift, or --format json for the evidence block, which lists the drifted configuration keys and affected environments), and the Console’s environment views. Accepting drift as an intentional exception has no CLI surface — do it through the Console. Tracked as CLI-2 in docs/implplan/SPRINT_20260727_003_Cli_release_environment_command_surface.md.

Docker Compose

# View the current drift report (evidence lists the drifted keys)
stella doctor run --check check.environment.drift --format json

# Compare specific configuration between environments
diff <(docker exec stellaops-staging cat /app/appsettings.json) \
     <(docker exec stellaops-prod cat /app/appsettings.json)

# Reconcile by redeploying from the canonical source
docker compose -f docker-compose.stella-ops.yml up -d --force-recreate <service>

Mark intentional drift as accepted from the Console; there is no CLI command for it.

Bare Metal / systemd

# View drift report
stella doctor run --check check.environment.drift --format json

# Compare config files between environments
diff /etc/stellaops/staging/appsettings.json /etc/stellaops/prod/appsettings.json

# Reconcile by copying from source of truth
sudo cp /etc/stellaops/staging/appsettings.json /etc/stellaops/prod/appsettings.json
sudo systemctl restart stellaops-<service>

Kubernetes / Helm

# View drift between environments
stella doctor run --check check.environment.drift --format json

# Compare Helm values between environments
diff <(helm get values stellaops -n stellaops-staging -o yaml) \
     <(helm get values stellaops -n stellaops-prod -o yaml)

# Reconcile by redeploying with consistent values
helm upgrade stellaops stellaops/stellaops -n stellaops-prod \
  -f values-prod.yaml

# Compare ConfigMaps
kubectl diff -f configmap.yaml -n stellaops-prod

Verification

stella doctor run --check check.environment.drift

check.environment.deployments— drift can cause service failures after redeployment
check.environment.secrets— secret configuration differences between environments
check.environment.network.policy— network policy drift is a security concern

See the Doctor reference for the full check catalog, CLI usage, and export bundles.