Skip to main content
By the end of this guide, one secret is declared once and has a different value in each environment: a local file on your machine for dev, and the hosted store for prod. You will set the prod value without it touching your shell history, confirm nobody can read it back, prove the app receives it, and rotate it. A secret is a name in your deploy config and a value in each environment’s store, so the code never changes between environments. Secrets is the reference for the hosted store and the console’s Secrets page.

Before you begin

1

Declare the secret once

Name the variable and say it comes from the environment’s store. In an adopted app that is forge.ManagedSecret in deploy/kcl/workloads.k, which every environment imports:
deploy/kcl/workloads.k
In a Forge Go API, mark the config field sensitive: true instead (Configuration). A workload receives only the secrets it declares.
2

Set the dev value in the local file store

Dev’s main.k declares secret_provider = forge.FileSecrets {path = "secrets/dev.yaml"}. secret set reads the value from stdin and writes it there:
terminal
Output (trimmed)
The file is mode 0600 and gitignored, so dev values never reach git. reliant forge env up dev hands each process the values it declares.
3

Set the prod value in the hosted store

The same command with --env prod writes to the hosted store instead. It works before the first deploy and creates the environment record on first write:
terminal
Output
Pipe from your password manager’s CLI rather than typing the value; there is no flag that takes it. Before a prod deploy, secret list --env prod is the check: a declared name shows MISSING until it is set, and a deploy that needs it fails.
4

Confirm nothing reads it back

There is no command that returns a hosted value, and env exec refuses hosted workloads:
terminal
Output
The store refuses reads below the CLI too (Hosted secrets are write-only). Keep your own copy of anything you cannot regenerate.
5

Deploy and verify the app receives it

Deploy, then ask the app whether the variable is set. The sample endpoint returns a boolean and the first 8 hex characters of the value’s SHA-256, never the value:
terminal
Output (trimmed)
6

Rotate the value

Setting an existing name writes a new version. That is rotation; there is no separate command:
terminal
Output
The running app answered with the new fingerprint about 15 seconds after the write, with no deploy: the platform rolls the workloads that read a changed secret. Rotate at the source first (issue the new key at the provider), set it here, then revoke the old key once the new fingerprint answers.
An environment marked protected asks an admin for an emailed one-time code before any value changes, and an automation token cannot change it at all. The security model explains the step-up; it was not exercised in this guide’s run.

What this does not do

  • It does not show or recover a value. A lost value is rotated at its source.
  • It does not share values between environments. Staging and prod each need their own secret set.
  • reliant forge env secrets verify is not a check for hosted secrets. It compares Secrets in your own Kubernetes cluster with an external store during a move to External Secrets, and on a hosted env it prints the env declares no store-backed ExternalSecret (forge.StoreSource): there is nothing to verify. Use secret list instead.

Troubleshooting

You ran a secret subcommand that does not exist, such as secret get --env prod NAME. The subcommands are set, unset, list, ensure, import, migrate, allow, deny and access; none returns a value.
The name is declared but nothing is stored for that environment. Set it with secret set --env <env>, then deploy.

Next steps

Add a custom domain with HTTPS

Serve the same prod environment on a hostname you own.

Secrets

Versions, delete versus destroy, and the console’s Secrets page.

Security model

Why values are write-only, and how step-up and workflow access lists work.

Custom domains

The domain and binding model behind forge cloud domain.