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.
To add a project variable, run the following command:
upsun variable:create --level project --name <VariableBlock name="VARIABLE_NAME" /> --value <VariableBlock name="VARIABLE_VALUE" />
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:
OptionCLI flagDefaultDescription
JSON--jsonfalseWhether the variable is a JSON-serialized value (true) or a string (false).
Sensitive--sensitivefalseIf set to true, the variable’s value is hidden in the Console and in CLI responses for added security. It’s still readable within the app container.
Runtime--visible-runtimetrueWhether the variable is available at runtime.
Build--visible-buildtrueWhether the variable is available at build time.
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: 
upsun variable:create --level project --name foo --value bar --visible-build true --visible-runtime false
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: 
upsun variable:update foo --visible-build false --visible-runtime true
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:
upsun variable:create --level environment --name <VariableBlock name="VARIABLE_NAME" /> --value <VariableBlock name="VARIABLE_VALUE" />
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:
OptionCLI flagDefaultDescription
Inheritable--inheritabletrueWhether the variable is inherited by child environments.
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: 
upsun variable:create -e main --name paypal_id --inheritable false --sensitive true
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: 
upsun variable:create -l environment -e main --prefix env: --name NODE_ENV --value production --visible-build true --inheritable false
upsun variable:create -l environment -e staging --prefix env: --name NODE_ENV --value development --visible-build true --inheritable true
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
export PATH="/app/vendor/bin:${PATH}"
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
URL=$(echo $PLATFORM_ROUTES | base64 --decode | jq -r 'to_entries[] | select (.value.id == "api") | .key')
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
if [ -f "deploy/environment.tracker.txt" ]; then
    echo "File found."
    export DEPLOY='Friday'
else
    echo "File not found."
    export DEPLOY='Never on a Friday'
fi
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: 
protocol version mismatch -- is your shell clean?
(see the rsync man page for an explanation)
rsync error: protocol incompatibility (code 2) at .../rsync/compat.c(61) [receiver=2.6.9]

[ProcessFailedException]
The command failed with the exit code: 2
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
export APP_DATABASE_HOST="${DATABASE_HOST}"
export APP_DATABASE_USER="${DATABASE_USERNAME}"
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 March 10, 2026