> For the complete documentation index, see [llms.txt](https://docs.release.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.release.com/reference-documentation/application-settings/default-environment-variables.md). # Default environment variables How to create and manage default environment variables for your Release environments ## Why to use environment variables Environment variables hold the environment-specific information that an application needs at runtime. For instance, a web application deployed in a production environment has to know how to access the production database. The same application running in a staging environment would have to know about a staging database instead. By storing configuration as environment variables instead of in code, you'll make your applications portable, secure, and easy to deploy on Release environments. ## How to create default environment variables for your environments When you create a new application, Release generates a default environment variables file, based on your code. For example, if your repository has a `docker-compose.yml` file, Release will populate the default environment variables for your new application based on the environment variables in that file. If your repository does *not* have a `docker-compose.yml` file, you can create your Release application's default environment variables manually, by editing your application's settings. ## How to edit an application's default environment variables To edit the default environment variables for an application, visit the application's App Settings page, then click the **Environment Variables** button. ![Edit the default environment variables](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-6607ff7c74a7918320835f0cae1de8504c4b51e1%2Fdefault-environment-variables.png?alt=media) This opens a YAML editor, which you can use to edit your default environment variables file. ## Default environment variables file structure A Release application's default environment variables file is formatted in YAML, and consists of three sections: | Section | Type | Required | Description | | ------------------------------------------------------------------ | :---: | -------- | --------------------------------------------------------------------------------------------- | | [`mapping`](#mapping-environment-variables-in-the-mapping-section) | Hash | false | Maps [Release variables](#releases-environment-variables) to your app's environment variables | | [`defaults`](#the-defaults-section) | Array | true | Default environment variables for your app | | [`services`](#the-services-section) | Hash | false | Service-specific environment variables | Here's an example of a default environment variables file: ```yaml mapping: COMMIT_HASH: RELEASE_COMMIT_SHA AWS_REGION: RELEASE_CLUSTER_REGION defaults: - key: POD_NAME from: pod_name - key: DEFAULT_LANG value: en - key: DB_HOSTNAME value: db services: admin: - key: DB_USERNAME value: admin_rw - key: DB_PASSWORD secret: true frontend: - key: NAMESPACE from: namespace - key: DB_USERNAME value: user_ro - key: DB_PASSWORD secret: true ``` Environment variables consist of a key, either a `value` or a `from` field (but not both), and an optional `secret` flag. Mark an environment variable as secret using `secret=true`. Secrets are encrypted at rest in a vault and hidden in the UI. You may also import secret environment variables from external secrets managers. See the [instructions here ](/reference-documentation/environment-settings/environment-specific-environment-variables/secrets.md)for more on secrets. The `from` field allows you to inject Kubernetes pod and node metadata as environment variables using the Kubernetes Downward API, instead of providing a static `value`. ## Individual environment variable schema | Field | Type | Required | Description | | -------- | :------------: | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `key` | String | True |

The environment variable's name.
It is convention to use uppercase names for environment variables.
Example: DB\_USERNAME

| | `value` | String or Null | False\* |

The value for this environment variable.
\*Required if from is not specified and secret is false.
Mutually exclusive with from.
If secret is true, this field is optional, and Release defaults to the previously saved value if this field is omitted.

| | `from` | String | False\* |

Injects Kubernetes pod/node metadata as the environment variable value.
\*Required if value is not specified.
Mutually exclusive with value.
Valid values: pod\_name, pod\_ip, host\_ip, namespace, node\_name

| | `secret` | Boolean | False |

Value is secret and should be encrypted. Value will be hidden from Release UI.
Defaults to false.

| Here's an example of three environment variables using `value`: ```yaml defaults: - key: DEFAULT_LANG value: en - key: DB_HOSTNAME value: db - key: DB_PASSWORD value: secret: true ``` ### Using the `from` field for Kubernetes metadata Instead of providing a static `value`, you can use the `from` field to inject Kubernetes pod and node metadata. This is useful for debugging, logging, and monitoring purposes. Here's an example using the `from` field: ```yaml defaults: - key: RELEASE_NAMESPACE from: namespace - key: POD_NAME from: pod_name - key: POD_IP from: pod_ip - key: HOST_IP from: host_ip - key: NODE_NAME from: node_name - key: DATABASE_URL value: postgres://localhost:5432/mydb ``` In this example: * `RELEASE_NAMESPACE` will contain the Kubernetes namespace the pod is running in * `POD_NAME` will contain the name of the pod * `POD_IP` will contain the pod's IP address * `HOST_IP` will contain the host node's IP address * `NODE_NAME` will contain the name of the node the pod is running on * `DATABASE_URL` uses a traditional static value You can also use `from` in the `services` section: ```yaml services: backend: - key: SERVICE_NAMESPACE from: namespace - key: SERVICE_POD_IP from: pod_ip - key: BACKEND_SECRET value: backend-secret-value secret: true ``` ## How Release uses an application's default environment variables file When you create a new environment, Release uses the application's default environment variables file to generate an environment-specific environment variables file for your new environment. Think of an application's default environment variables file as the blueprint for each new environment's environment variables. ## Release's environment variables Apart from the environment variables lifted from your `docker-compose.yml`, and the variables you created yourself, Release provides additional environment variables. You can [map Release's environment variables](#mapping-environment-variables-in-the-mapping-section) to your app's environment variable names so that you do not need to change your application's code when deploying on Release or elsewhere. Environment variables provided by Release have names that start with `RELEASE_`. Here's an overview of the variables provided by Release: ### `RELEASE_ACCOUNT_ID` **Release account ID:** Each Release account has a unique numerical identifier. ### `RELEASE_APP_NAME` **Release application name:** Each Release application has a unique string identifier. ### `RELEASE_BRANCH_NAME` **Git branch:** The name of the git branch from your repository deployed to this environment. ### `RELEASE_BUILD_ID` **Release build ID:** Each Release build has a unique numerical identifier. ### `RELEASE_CLOUD_PROVIDER` **Cloud provider:** The cloud provider that hosts this environment. For example, `aws` or `gcp`. ### `RELEASE_CLUSTER_REGION` **Cloud provider region:** The cloud provider region for this environment. For example, `us-west-2` or `us-east-1`. ### `RELEASE_COMMIT_SHA` **Git hash:** The SHA hash of the git commit deployed in this environment. This refers to a commit in your repository. ### `RELEASE_COMMIT_SHORT` **Short git hash:** The short hash of the git commit deployed in this environment. This refers to a commit in your repository. ### `RELEASE_CONTEXT` **Release context:** Refers to the Kubernetes context for this deployment. ### `RELEASE_DOMAIN` **Release domain:** If you do not have a custom domain set up on your Release account, this will be `rls.sh`. ### `RELEASE_ENV_ID` **Release environment ID:** Each Release environment has a unique string identifier. ### `RELEASE_RANDOMNESS` **Release random string:** This short random string is used to create unique links. ### Release's service-specific environment variables Release also provides environment variables specific to each service in your environment. When creating these variables, Release converts the service name to uppercase and prepends this to each service-specific environment variable's name. For example, if you have two services, `admin` and `frontend`, Release provides environment variables as follows: #### `ADMIN_COMMIT_SHA` **Short git hash:** The SHA hash of the git commit deployed for this service. This refers to a commit in your repository. #### `ADMIN_COMMIT_SHORT` **Short git hash:** The short hash of the git commit deployed for this service. This refers to a commit in your repository. #### `ADMIN_INGRESS_HOST` **Ingress hostname:** The hostname of the instance/load balancer for this service, accessible to the internet. #### `ADMIN_INGRESS_URL` **Ingress URL:** The public URL for this service. #### `FRONTEND_INGRESS_URL`, `FRONTEND_INGRESS_HOST` etc. The equivalent environment variables are provided for the `frontend` service in this example. ## Mapping environment variables in the `mapping` section You can use the `mapping` section to map existing environment variables to new environment variables. ### Mapping Release's variables By mapping [Release's environment variables](#releases-environment-variables) to your app's environment variables, you do not need to reference Release-specific environment variable names in your code. In the example below, your code expects an environment variable called `AWS_REGION`. Mapping allows you to pass `RELEASE_CLUSTER_REGION` to your application, adding its value to a new environment variable called `AWS_REGION`. ```yaml mapping: COMMIT_HASH: RELEASE_COMMIT_SHA AWS_REGION: RELEASE_CLUSTER_REGION REACT_APP_ADMIN_BASE_URL: ADMIN_INGRESS_URL REACT_APP_FRONTEND_BASE_URL: FRONTEND_INGRESS_URL ``` ### Mapping your app's environment variables The `mapping` section also allows you to reference your app's environment variables. In the example below, `REACT_APP_ADMIN_PATH` gets its value from `DEFAULT_ADMIN_PATH`: ```yaml defaults: - key: DEFAULT_ADMIN_PATH value: /admin/ mapping: REACT_APP_ADMIN_BASE_URL: ADMIN_INGRESS_URL REACT_APP_ADMIN_PATH: DEFAULT_ADMIN_PATH ``` ### Combining existing variables and strings to create new variables Release's `mapping` section allows you to create new environment variables through string interpolation. In the example below, `ADMIN_FULL_URL` is created by concatenating `ADMIN_INGRESS_URL` and `DEFAULT_ADMIN_PATH`: ```yaml defaults: - key: DEFAULT_ADMIN_PATH value: /admin/ mapping: ADMIN_FULL_URL: "${ADMIN_INGRESS_URL}${DEFAULT_ADMIN_PATH}" ``` You can also provide default values if an environment variable is unset or empty. In the example below, if `MAYBE_EMPTY_BASE_URL` does not exist, or is empty, the default `https://example.com` will take its place. ```yaml mapping: ADMIN_FULL_URL: "${MAYBE_EMPTY_BASE_URL:-'https://example.com'}/admin/" ``` The syntax to indicate a default is based on *parameter expansion* in bash: `${parameter:-defaultvalue}`, but unlike in bash, `defaultvalue` is interpreted as a string. `defaultvalue` can't reference an environment variable. String interpolation and parameter expansion is limited to the `mapping` section of your environment variables YAML. ## The `defaults` section The `defaults` section contains environment variables that are available to all services in an environment. Here's an example of the defaults section: ```yaml defaults: - key: DEFAULT_LANG value: en - key: DB_HOSTNAME value: db ``` ## The `services` section Use the `services` section to define environment variables for specific services only. Each service in this section has one or more environment variables. Here's an example of service-specific environment variables: ```yaml services: admin: - key: DB_USERNAME value: admin_rw - key: DB_PASSWORD secret: true frontend: - key: DB_USERNAME value: user_ro - key: DB_PASSWORD secret: true ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.release.com/reference-documentation/application-settings/default-environment-variables.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.