> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage production secrets per environment

> Give each environment its own secret values: a gitignored file for dev, the write-only hosted store for prod, set from stdin and rotated without a redeploy.

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](https://docs.reliantlabs.io/hosting/secrets.md) is the reference for the hosted store and the console's **Secrets** page.

## Before you begin

* A Forge project whose `prod` environment is bound to [Reliant hosting](https://docs.reliantlabs.io/hosting/overview.md). [Deploy a Go API with managed Postgres](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md) or [Deploy an existing app from its Dockerfile](https://docs.reliantlabs.io/guides/forge/bring-existing-app-any-language.md) gets you there. This guide uses a small Node API adopted with `--kind app`.
* The admin role in the organization, or an automation token with `secret:write` ([who can set a secret](https://docs.reliantlabs.io/hosting/secrets.md#who-can-set-a-secret)).
* Billing on the organization for the deploy step. Setting a secret needs no billing and starts nothing.
* Forge v1.6.1 or later (`reliant forge --version` inside the project).

**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:

```python deploy/kcl/workloads.k theme={null}
env = {
    PORT = "3000"
    PAYMENTS_API_KEY = forge.ManagedSecret {name = "PAYMENTS_API_KEY"}
}
```

In a Forge Go API, mark the config field `sensitive: true` instead ([Configuration](https://docs.reliantlabs.io/forge/adding-features.md#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:

```bash terminal theme={null}
openssl rand -hex 16 | reliant forge env secret set --env dev PAYMENTS_API_KEY
reliant forge env secret list --env dev
git check-ignore -v secrets/dev.yaml
```

```text Output (trimmed) theme={null}
set PAYMENTS_API_KEY (32 bytes) in …/app/secrets/dev.yaml
secret store (file): …/app/secrets/dev.yaml
  PAYMENTS_API_KEY                   set
.gitignore:3:secrets/	secrets/dev.yaml
```

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:

```bash terminal theme={null}
openssl rand -hex 24 | reliant forge env secret set --env prod PAYMENTS_API_KEY
reliant forge env secret list --env prod
```

```text Output theme={null}
PAYMENTS_API_KEY: created v1 (48 bytes) in hosted env "prod" at https://admin.reliantapi.com
secret store (hosted): https://admin.reliantapi.com
  PAYMENTS_API_KEY                   set (v1)
```

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:

```bash terminal theme={null}
reliant forge env secret get PAYMENTS_API_KEY
reliant forge env exec prod -- printenv PAYMENTS_API_KEY
```

```text Output theme={null}
unknown command "get" for "reliant forge env secret"
workload "api" uses hosted: env exec only supports OnHost/OnCompose; use your hosting provider's exec tool or kubectl exec for remote workloads
```

The store refuses reads below the CLI too ([Hosted secrets are write-only](https://docs.reliantlabs.io/deep-dives/security-model.md#6-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:

```bash terminal theme={null}
reliant forge env deploy prod --yes
curl -s https://<your-url>/
```

```text Output (trimmed) theme={null}
  url api: https://fair-stoat.reliantlabs.dev (served through the regional ingress, no CDN)
Rollout of 20261120.103810-133d08e5940c to prod: SUCCEEDED
{"payments_api_key_set":true,"fingerprint":"983dd05c"}
```

**6. Rotate the value**

Setting an existing name writes a new version. That is rotation; there is no separate command:

```bash terminal theme={null}
openssl rand -hex 24 | reliant forge env secret set --env prod PAYMENTS_API_KEY
curl -s https://<your-url>/
```

```text Output theme={null}
PAYMENTS_API_KEY: rotated to v2 (48 bytes) in hosted env "prod" at https://admin.reliantapi.com
{"payments_api_key_set":true,"fingerprint":"58a0ef86"}
```

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.

> [!NOTE]
>
> 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](https://docs.reliantlabs.io/deep-dives/security-model.md#6-hosted-secrets-are-write-only) 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

> [accordion] unknown flag: --env
>
> 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.

> [accordion] PAYMENTS\_API\_KEY  MISSING
>
> The name is declared but nothing is stored for that environment. Set it with `secret set --env <env>`, then deploy.

## Next steps

> [card] [Add a custom domain with HTTPS](https://docs.reliantlabs.io/guides/hosting/custom-domain-https.md)
>
> Serve the same prod environment on a hostname you own.

> [card] [Secrets](https://docs.reliantlabs.io/hosting/secrets.md)
>
> Versions, delete versus destroy, and the console's Secrets page.

> [card] [Security model](https://docs.reliantlabs.io/deep-dives/security-model.md)
>
> Why values are write-only, and how step-up and workflow access lists work.

> [card] [Custom domains](https://docs.reliantlabs.io/hosting/custom-domains.md)
>
> The domain and binding model behind `forge cloud domain`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.