How syncs work
A sync moves keys one way, for one environment, under a policy you pick for names that already exist.
A connection holds a credential. A sync is one mapping on that connection: one direction, one of your environments, one place in the other system. A connection can carry as many mappings as you need.
The two directions
| Direction | What it does |
|---|---|
import | Reads names and values out of the store into penv |
export | Writes names and values from penv into the store |
A provider page names the directions that provider supports. Some can only be written to, because the vendor publishes no way to read a stored value back. Those pages say so.
What happens to a name that exists
The conflict policy is the answer to "this name is already there". Import and export have separate sets, because the question is a different one in each direction.
| Import policy | What it does |
|---|---|
skip_existing | Leaves the penv value alone and moves on |
new_version | Writes the incoming value as a new version, and the old one stays in history |
fail | Stops the run and changes nothing |
| Export policy | What it does |
|---|---|
create_only | Writes names the store does not have, and touches nothing else |
overwrite | Writes every name penv holds, replacing what is there |
overwrite_and_prune | Writes every name penv holds, then deletes names penv has no key for |
overwrite_and_prune deletes values in the store that penv does not know about. Read the preview before you apply that one.
When a written value goes live
An export can succeed and still change nothing the app can see, because most platforms bind values at deploy time. Every provider declares which of these it is, and its page says so.
| Activation | What it means |
|---|---|
immediate | The running app sees the new value at once |
on-next-deploy | The value waits there and arrives with your next deploy |
on-request | The value waits there, and penv can deploy to activate it. The sync form asks you first |
restart-on-write | Writing restarts the workload |
on-request is a question rather than a default, because redeploying production as a side effect of a secret sync is your call.
Preview, then apply
Preview is a dry run. It reads names alone and shows you the plan: what would be created, what would be replaced, what would be deleted. Apply runs the plan you just read.
Every run is recorded, so you can open a mapping and see what moved and when. Preview and apply both land in the audit log, as integration.run_enqueued and integration.run_applied.
Values leave penv on an export
An export mapping asks you to acknowledge that values are going somewhere penv does not control. After that, they live under the other system's access rules and its own logs, and penv can no longer say who read them.
The server can decrypt your values to serve your machines. That is what makes penv pull work, and it is also what makes an export possible.
Permissions
Verifying a connection probes for the permissions the provider page lists. A permission marked blocking fails the check outright. The rest degrade one feature and say which.
Next: connect methods.