Rotate a value

Values are append-only versions, so replacing one is an ordinary write. penv set puts the new value in as the next version and the old version stays in the history.

From the command line

printf %s "$NEW_VALUE" | penv set STRIPE_SECRET_KEY --env production

set reads the value from a pipe, or types it with the echo off when you are at a terminal. It refuses a --value flag outright, because the shell would keep it in its history. The refusal even prints the pipe to use.

It answers with the version it created:

set version 4 STRIPE_SECRET_KEY in acme/api-gateway/production

A key your schema never declared gets a block appended to .env.schema, carrying the type the value implies and none of the value itself. Everything already in the file is left alone.

penv unset KEY removes a value and keeps the block, because the schema says what may exist rather than what does. That write is the whole of rotation. The binary carries no rotate command.

From the console

Open the environment, find the row, and choose Set New Version from its menu. That opens the single-parameter form with the address locked, so the only editable field is the value. The field starts empty and is never seeded from what is stored. The button is Save New Version.

Details & History on the same menu shows the append-only version list for that key, with the version numbers and when each was set.

Who is allowed to

Writing a value needs secret:write at that environment. Reading one back needs secret:reveal plus confirming it is you. Both writes land in the record of who did what, so the row names the person and the version.

What @rotate does today

@rotate=<duration> marks a key in the schema:

# @type=string(startsWith=sk_) @rotate=90d
STRIPE_SECRET_KEY=

penv validates that the value is a duration such as 90d, keeps it in the file when it rewrites one, and sends it to the cloud with that key's stored schema. Nothing in the binary acts on it: it reminds nobody and it expires nothing. Treat it as a note your team reads and your tooling can query.

A key the cloud mints for itself

Some keys are minted on request rather than stored. A write to one answers 409 dynamic, and penv says the key is minted by an engine and to edit it in the console. Rotating one means changing the engine it comes from. See short-lived values.

Do it in order

1. Mint the new value at whoever issues it, leaving the old one working.
2. printf %s "$NEW_VALUE" | penv set KEY --env production, or use Set New Version in the console.
3. Read back the version number penv printed and confirm it is one higher than before.
4. Redeploy, or restart the processes that read that key, so nothing is still holding the old value.
5. Watch for failures for as long as your slowest consumer takes to restart.
6. Retire the old value at the issuer. Until you do, both work.
7. Open the audit log and confirm the write is there, with your name on it.

The record of who did what