Docs menu

Secrets

Secrets are set per environment and reach your app as environment variables. Saving a change redeploys your app with the new values.

On this page

Secrets are how your app gets its configuration: database URLs, API keys, feature flags, anything you don't want in the repo. They're set per environment, encrypted at rest, and reach your app as environment variables.

Setting secrets#

Open the application's Settings page and scroll to Secrets. Add, edit, or remove Key / Value rows. Values are hidden until you click a row's reveal button.

The Secrets panel with paired key/value rows, one value masked and one revealed, per-row remove buttons, Add More, and Save

Hit Save and every change is applied together: new keys are added, changed values updated, and removed keys deleted. Either the whole save lands or none of it does.

Where your app sees them#

  • During the build. Your build can read secrets, so tools like npm, pip, bundle, and composer can use a token for a private registry, or a flag can change how assets compile. A secret replaces a build default of the same name. Keys starting with PRIMCLOUD_ are never passed to the build.
  • At runtime. Every process in every formation, and every task, starts with your secrets as environment variables. Read them the way you would locally: process.env.X, os.getenv('X'), ENV['X'], getenv('X').

Saving redeploys your app#

Each save creates one deployment, however many keys you changed. It releases your live build again with the new values, without rebuilding and with no dropped requests.

  • Every save deploys. Two saves in a row make two deployments, so batch your changes into one save.
  • Before your first successful deploy, a save just stores the values. They apply when your app first deploys.
  • Canceling that deployment doesn't revert the values. They're stored the moment you save. To undo a change, edit it again. See Canceling a deployment.

Who can see them#

Anyone with access to the account that owns the application can reveal its secrets: just you on Standard and Pro, and the team's members on Team. Protect the account the way you would any secret store, with a unique password and 2-factor auth.

Variables Primcloud sets#

Your web, worker, and other formations, and your release process, also get these variables. A secret with the same name is replaced by Primcloud's value.

Variable What it is
PRIMCLOUD_APP_ID ID of the application.
PRIMCLOUD_APP_SLUG Slug of the application.
PRIMCLOUD_ENVIRONMENT_ID ID of the environment.
PRIMCLOUD_FORMATION_NAME Name of the formation this process belongs to (web, worker, …).
PRIMCLOUD_REGION Region the app runs in (us-east-1).
PRIMCLOUD_COMMIT Git SHA of the running code.
PRIMCLOUD_POD_ID Unique name of the running copy of this formation, useful for telling copies apart in logs.
PRIMCLOUD_RELEASE_VERSION Version of the running release (v1, v2, …), counting up with each successful release.
PRIMCLOUD_RELEASE_CREATED_AT When the running release was created.
PORT Port your web process must listen on (5000). Set on web only.

Apps in the languages Heroku supports also get Heroku's names for these, such as DYNO and HEROKU_APP_NAME; see What carries over from Heroku.

Important

Bind your web server to $PORT. Traffic only reaches that port, so an app hard-coded to 3000 or 8080 won't receive requests.