Secret migration policy

3 min readReferenceUpdated 2026-05-23

What you'll find here

The policy that decides what happens to secret-bearing fields during migration — the four outcomes, the runtime contract, dry-run behavior, and receipt expectations.

No implicit copying.

Migration workflows must never copy secret values from an adjacent tool, workflow engine, or configuration source into the target runtime. Unknown fields that contain secret material are blocked by default. A migration policy cannot authorize secret-value copying. Optional OS-keyring import is a separate, explicit operator-confirmed step that writes only to a secure credential backend and records a redacted receipt.

Outcomes

Outcome

Use for

Effect

redact

leakage prevention

Replace source value with a redaction marker in reports and receipts.

reference

handle only

Preserve only a non-secret reference identifier (e.g. vault key name).

reconfigure

operator action

Require the operator to recreate or bind the secret in the target environment.

block

stop

Stop the field or record from migrating until an explicit policy decision exists.

Runtime contract

SecretMigrationPolicy records source, policy envelope, evidence, receipts, and field-level rules. Each SecretMigrationPolicyRule defines source field, safe handling mode, reason, dry-run warning, and whether operator action is required.

evaluate_secret_migration returns a SecretMigrationDecision:

Source field

Outcome

Notes

Non-secret

allowed

No secret receipt required.

Matching secret rule

one of four

redacted / referenced / operator_reconfiguration_required / blocked.

Unmapped secret

blocked

Default for unknown secret-bearing fields.

Always copied_secret_value: false.

Every secret decision sets copied_secret_value to false.

Dry-run behavior

Import dry-run reports include warnings from the secret migration policy. Warnings describe the safe handling outcome without exposing the source value. Public docs and public receipts must not include local filesystem paths, credentials, private task names, or copied secret bytes.

Redacted Inventory

detect_secret_inventory scans nested source payloads for secret-like field names such as api_key, token, password, secret, and credential. The inventory records:

Source id

Field path

For example provider.api_key.

Value fingerprint

A truncated hash for correlation, not the value.

Value length

Enough for diagnostics without disclosure.

Optional keyring import

migrate_secret_inventory_to_keyring can write detected values to a secure OS credential backend only when the operator explicitly confirms the operation. Without confirmation, the function returns dry-run receipts and writes nothing. If the current backend is the file fallback or otherwise not secure, the import is blocked and the operator must reconfigure credentials manually.

Receipts

Secret migration receipts record:

Policy envelope

That governed the decision.

Classifying evidence

Safe handling outcome

Required operator action

When applicable.

Confirmation

That no secret value was copied.

Keyring target

When an explicit secure-backend import was confirmed.

Fingerprint

For correlation without logging the value.

What's next

ReferenceMigration mapsThe field-level mapping contract this policy gates.ReferenceImport dry-run reportsHow secret warnings reach operators.ADR0003 · Secret handlingThe references-not-values design.