OrbitsDocs
esc
    Open Orbits
    Build and deployEnvironment variables

    Environment variables

    Set keys and secrets per environment, mark them sensitive, reveal, import a .env file, delete with undo, pull them for local development, and redeploy to apply a change.

    Environment variables hold your app's configuration and secrets: API keys, database URLs, feature switches. They are available when the project builds and while it runs, and values are encrypted.

    Open a project's Environment variables page. Each row is one key, with the environments it applies to.

    Environments

    A variable applies to any mix of three environments:

    EnvironmentUsed by
    ProductionProduction deployments, including promoted ones.
    PreviewPreview deployments of other branches.
    DevelopmentYour own machine, through orbits env pull.

    New variables apply to Production and Preview unless you pick otherwise. A key has one value, shared by every environment it applies to.

    Add a variable

    Press Add a variable, give the Key and the value, tick the environments, and save. Keys use letters, digits and underscores and don't start with a digit, such as STRIPE_SECRET_KEY.

    Terminal
    $ orbits env add STRIPE_SECRET_KEY

    The CLI reads the value from standard input when it isn't on the command line, hidden at a terminal. In a script: printf %s "$VALUE" | orbits env add STRIPE_SECRET_KEY.

    A key that already exists can't be added again; edit it instead.

    Sensitive variables

    Sensitive is ticked by default. A sensitive value is write-only: "Nobody can read it back, only replace it." Not you, not an owner, not the API. The page shows no eye icon, Reveal value or copy for it, and orbits env pull leaves it out. You can only edit it by typing a new value.

    Untick Sensitive for values you need to read back. With the CLI, variables are sensitive by default too; --plain makes one readable.

    Whether a variable is sensitive is set when you add it and can't be changed afterwards. To change it, delete the variable and add it again.

    Reveal a value

    For a variable that isn't sensitive, Reveal value (or the eye icon) shows it, and the menu copies it. Every reveal is recorded in the team's activity with who did it and which key, never the value.

    The list shows a value in clear without revealing only when the variable isn't sensitive and its key is meant for the browser anyway: it starts with NEXT_PUBLIC_, NUXT_PUBLIC_, PUBLIC_, VITE_, REACT_APP_ or EXPO_PUBLIC_, or ends with _PUBLIC_KEY. Everything else shows dots until revealed.

    Terminal
    $ orbits env ls                 # keys and environments$ orbits env ls --show-values   # with readable values

    Edit a variable

    Choose Edit from the row's menu. The key is read-only ("To rename a key, add a new one and delete this one."). Type a new value, or leave the value empty to keep the current one and change only the environments. The new value is used from the next deployment.

    Import a .env file

    Press Import .env and drop a .env file or paste its contents. Each line becomes a variable, applied to the environments you pick. Keys that already exist are replaced, value and environments, in the environments you pick, and the dialog warns you which ones before you import.

    The Configure step of a new project has Import .env too, so you can bring your variables in before the first deploy.

    Delete and undo

    Choose Delete from the row's menu and type the key to confirm. The variable disappears at once, and the toast offers Undo for 10 minutes:

    Terminal
    $ orbits env rm STRIPE_SECRET_KEY$ orbits env restore STRIPE_SECRET_KEY   # within 10 minutes

    Restoring brings back the value and environments it had, unless a variable with that key has been added since. Deployments made after the delete don't get the variable.

    Redeploy to apply a change

    Variables are read when a deployment is built. Changing one doesn't touch deployments that are already running: they keep the values they were built with. After a change, the page shows a banner such as "You changed 1 variable. Redeploy so production picks it up.", with Redeploy to apply, and marks the changed rows New.

    Redeploy production to pick the change up. Variables a framework bakes into the browser bundle (NEXT_PUBLIC_*, VITE_* and so on) always need a rebuild to change. See redeploy.

    Pull variables for local development

    orbits env pull writes an environment's readable variables to a file for local development:

    Terminal
    $ orbits link$ orbits env pull .env.local

    It pulls Development by default and writes the file with mode 0600. Sensitive variables can't be read back, so they're left out, and the CLI names them so you know what's missing. It warns you if Git doesn't ignore the file. Keep .env.local out of Git; Next.js projects ignore it already. Every pull is recorded in the team's activity.

    What every deployment also gets

    Orbits adds a few variables to every deployment, unless you set a variable with the same name yourself:

    VariableWhat it is
    SITE_URLThe address the deployment is for: production's address for production, the deployment's own address for a preview.
    ORBITS_FLAGSThe key @useorbits/flags reads the environment's flags with.
    ORBITS_WORKFLOWSThe key @useorbits/workflows uses.
    ORBITS_API_URLThe Orbits API's address.

    Server apps also run with NODE_ENV=production and PORT, which your server should listen on. Builds run with CI=1.

    Limits

    Limit
    Variables per project1,000
    Variables in one import500
    Size of one value32 KiB
    Line breaks in a valueNot supported yet: such a variable is skipped, with a line in the build log

    Who can do what

    Owners, admins and members add, edit, delete, reveal and pull variables. Viewers see the keys and environments, never values.

    API tokens follow the same rules as the person who made them, with one more: a read token never reads a value. Reveal and pull are writes in the API, so they need a full token. See API tokens.

    The API is in environment variables.

    Was this page helpful?

    Updated