Environments & secrets

NuPaaS separates where your app runs (an environment) from what it is configured with (variables and secrets). Knowing which of the three storage layers a value belongs in is most of the work.

Three places values can live#

Environments#

An environment belongs to a project and optionally to a single service inside it. Each one carries a name, a type, a status, a protection level, and — once something is deployed to it — a URL and a current deployment.

Manage environments from /orgs/<org>/projects/<project>/environments. The available operations are create, update (rename or change protection level), sync, delete, and promote.

Environment variables#

Variables are attached to an environment, not to a project as a whole. From the panel you can add a variable, mark it as a secret, and delete it. From the CLI:

platform env list  --project <projectId>
platform env set   --project <projectId> --env production KEY=VALUE
platform env unset --project <projectId> --env production KEY

Reading an environment's variables returns three kinds of entry: variables the platform manages, references to a named org secret, and variables discovered on the running workload that the platform did not create. Discovered entries are always returned redacted — the platform reports that the key exists on the workload without reading its value back out.

Org-level named secrets#

A named secret lives at the organization level and is versioned. Names must start with a letter and may contain letters, digits, underscores and hyphens, up to 128 characters.

Named secrets support:

• create, with an optional description, tags and sync targets;
• list and read metadata, which never includes the value;
• read the value as a separate, separately-audited operation;
• update the description and tags;
• rotate — replace the value and increment the version — and delete.

Metadata reads and value reads are deliberately different operations so that the audit log distinguishes "someone listed the secrets" from "someone read this secret's value".

Linking a secret into an environment#

Rather than copying a secret's value into an environment variable, link it. The environment then holds a reference — the secret's name, namespace and key — and rotating the secret does not require touching every environment that uses it.

CI secrets#

A named org secret whose sync targets include CI is also written to your Forgejo Actions secrets, so build workflows can read it. These are organization-scoped, so no project is required:

platform env list  --ci
platform env set   --ci KEY=VALUE
platform env unset --ci KEY

platform env set --ci creates the org secret and marks it for CI sync in one step. Without --ci, the same commands require --project and operate on project environment variables instead.

Promoting between environments#

Promotion copies the state of a source environment onto a target environment. It takes two environment ids and is a distinct operation from deploying — see Promote and roll back for how promotion relates to deployment rollbacks and canaries.