Skip to main content
To set variables, determine which type of variable to use. Remember to take into account the order of precedence. All of the variables can also be overridden via script.

​
Set variables in your app

Set variables in code using the .upsun/config.yaml file. These values are the same across all environments and present in the Git repository, which makes them a poor fit for API keys and other such secrets. They’re better fits for uses such as configuration for consistent builds across every environment, including setting PHP configuration values. Application variables are available at both build time and runtime.

​
Create project variables

Add secrets for all environments in project variables using the Console or the CLI. For example, you may need to vary API credentials between production and other environments. To do so, set the non-production credentials as a project variable and then override these credentials for the production environment by setting a variable specific to that environment. Third-party API keys are common candidates for this — for example, a payment gateway credential, or the LLM provider API key (ANTHROPIC_API_KEY or OPENAI_API_KEY) required by the Upsun performance agent.
To add a project variable, run the following command:
To specify other options, use the flags for variable options.
When naming variables, be sure to take variable prefixes into account. In particular, to expose a variable as its own environment variable, use the prefix env:.

​
Variable options

Variables have several Boolean options you can set in the Console or the CLI: So if you want the foo variable to be visible at build time but hidden during runtime, you can set it by running the following command:
You can also change the variable options after you create them (except for sensitive values, which can’t be set to non-sensitive). For example, to make the foo variable visible at runtime and hidden during the build, run the following command:

​
Limiting variables to specific applications

If you want the foo variable to be available only to certain applications, you can limit its scope using the --app-scope option:
Where frontend1 and frontend2 are the names of your applications. Note that for changes to project variables to have effect, you need to redeploy your environments.

​
Create environment-specific variables

Set variables for specific environments using the Console or the CLI. Variables can be inherited or overridden from parent environments and project variables. See more on overriding values.
To create a variable for the current environment, run the following command:
To specify the environment for the variable, use the -e flag to specify its name. To specify other options, use the flags for variable options.
When naming variables, be sure to take variable prefixes into account. In particular, to expose a variable as its own environment variable, use the prefix env:.

​
Environment variable options

Environment variables share all of the options available for project variables. Environment variables have one additional option: This option is useful for setting production-only values such as credentials. For example, to set a PayPal secret value for only the main branch and have it not be readable elsewhere, run the following command:
Other environments don’t inherit it and get either a project variable of the same name if it exists or no value at all. Note that changing an environment variable causes that environment to be redeployed so the new value is available. But child environments are not redeployed. To make the new value accessible to those environments, trigger a redeploy.

​
Example environment variable

Environment variables are a good place to store values that apply only on Upsun and not on your local development environment. This includes API credentials for third-party services, mode settings, and which server (development vs. production) to use. One example would be to define a Node.js application’s build on a production branch (NODE_ENV=production), but use development mode (NODE_ENV=development) for each of your preview environments. Assuming you have a main environment for production and a staging environment with more child environments for development, run the following commands:
Now NODE_ENV is production on the default branch but development on staging and each of its child environments. Note that build visible environment variables change the application’s build configuration ID: value updates trigger a rebuild of the application in the same way that a commit would.

​
Set variables via script

You can also provide a .environment file as in your app root. This file runs as a script in dash when the container starts and on all SSH logins. It can be used to set any environment variables directly, such as the PATH variable. For example, the following .environment file allows any executable installed in the vendor/bin directory (such as executables installed using Composer) to be run regardless of the current directory:
.environment
You can also dynamically define environment variables based on the current environment. For example, you might want to get the defined route with the id api for the current environment. To define it as the URL environment variable, you might add something like:
.environment
Note that the file is sourced after all other environment variables above are defined and so they’re available to the script. This also means the .environment script has the last word on environment variable values and can override anything it wants to.

​
Testing .environment scripts

You may find that a command that works during an SSH session provides a bad substitution error when placed in a .environment file. Remember, .environment is sourced using dash, not bash. When testing your .environment logic, be sure to first enter a dash session in your terminal or within the SSH session. When testing, you might print to stdout (using an echo or printf command) to check what’s happening. The following example looks for a deploy/environment.tracker.txt file. It displays a different message if it’s found or not, which helps you track what variables are being set.
.environment
While sanity checks like this are useful during troubleshooting, you shouldn’t include such commands in your final code. Because the .environment file is run at the start of an SSH session, the message is printed at the start of the session. Even when your SSH command executes successfully, you might later attempt to download data from one of your mounts, such as by using the CLI command upsun mount:download. When you do, you see this error:
This failure comes because mount:download and rsync don’t expect output when the SSH connection is made. To solve the issue, remove the printed output from your .environment file.

​
Map variables

If your app needs different names for environment variable than those set by Upsun, which is common for database connections, map the Upsun’s variable names to those required by the application via a shell script. You can obtain relationship information through the service environment variables themselves, or through the PLATFORM_RELATIONSHIPS environment variable. For example, if your application has a relationship named database to a database service named mariadb:
.environment
This sets environment variables with the names your app needs, and the values from service environment variables.

​
When to use .env files

Upsun does not read .env files, as conventionally they are not committed to Git. You can use these for local development, but they will not be sourced on any Upsun environment. Typically, you can add .env to your .gitignore file so that its contents can vary for different developers. Read more about the use cases for .env files.
Last modified on July 17, 2026