Manage Cloud Env

Add the key and establish the native connection

• Healthy existing connection: write the key to its appropriate Doppler parent or child. Leave the Porter app attached to the environment's child config; do not point it directly at the incomplete shared parent.
• Broken existing connection: repair and verify the native Doppler sync, then write the key. A disconnected integration is not a reason to duplicate keys in Porter. Follow the runbook's scoped service-token and operator-refresh procedure.
• No associated Doppler project/connection: create the owning Doppler project, a dedicated shared parent, and the deployment child config. Do this even for a miniapp with only one environment. Populate required environment-specific settings in the child, enable inheritance, and create/attach a native Porter Doppler group using a read-only service token scoped to that child. For an already-running app, preserve and verify its effective values before replacing its configuration sources. Update the managed deployment contract and owning deployment files as applicable.

The CLI supports creating a dedicated shared environment/root config and enabling inheritance. Use explicit verified identifiers, preserve existing inheritance, and check current CLI help before running these example operations:

doppler environments create 'Shared provider credentials' shared --project PROJECT
doppler configs update --project PROJECT --config shared --inheritable=true --yes
doppler configs update --project PROJECT --config CHILD --inherits PROJECT.shared --yes

--inherits replaces the inheritance list: include existing parents in the intended precedence order. Populate shared values before attaching consumers. Write secrets through private structured API bodies or a supported private input path, keeping values out of shell arguments, logs, and tracked files.

When migrating existing copies, save recoverable previous values/configuration, attach the parent first, verify the resolved child config, then remove only the selected child copies. Re-read the complete resolved config: only intended values may change. Branch configs can also inherit root values; verify actual resolution instead of assuming that deleting a branch copy removes the key altogether. Keep a rollback path until the affected behavior is verified.

A shared-parent edit affects every current inheritor. Inspect those consumers before changing an existing shared value. Respect the user's authorized rollout scope. For staged migrations, do dev first, wait for the requested confirmation, then staging, then production; production's resolved values must remain identical when the change only moves storage into inheritance. Do not migrate other environments or restart deliberately stopped apps as a side effect of a feature.

Verify the deployed result

Verify the intended SecretStore and ExternalSecret are Ready=True and have an advancing, recent successful refresh. Privately compare the linked group's values with the resolved Doppler config. Then verify running process values; environment variables are startup snapshots. If a rollout is needed, use the owning deployment workflow and preserve the current image/topology for a configuration-only change.

Check backend readiness and the affected provider operation. Do not treat an old green deploy, a successful secret write, or a refreshed group as proof that the feature works. Report the actual project/config, parent, key names, rollout scope, completed checks, and any remaining user test. Never report secret values.

Use the existing deployment source guard and scoped read-only health checks where applicable; do not disable them to accommodate a manual override. Update the managed contract when a new app, config/group mapping, or required key is introduced.

Porter overrides are the last resort

Before considering any override, check the correct Doppler project, config, inheritance, sync credential, linked group, and refresh status. A missing project, missing key, stale process, or repairable sync must be addressed through the paths above. Do not use porter env set to bypass that work or resurrect the retired manual-mirroring scripts.

Only use a temporary application override when the user explicitly requests that exception or has already authorized it for a demonstrated blocker with no supported Doppler path. Explain the blocker, affected keys/environment, and cleanup/rollback plan. Existing source guards still apply; do not bypass them. Keep Doppler as the authoritative destination and remove the exception after verifying native sync.

Reference: Doppler Config Inheritance.