Variables

Service variables are provided whenever you build, deploy, or run railway run. When defined, they are made available to your application at runtime as environment variables.

Variables are made available in the following scenarios:

  • The build process for each service deployment,
  • The running service deployment, and
  • The command invoked by railway run <COMMAND>.

Defining Variables

Variables can be added via the Railway Dashboard by navigating to a service's "Variables" tab.

Screenshot of Variables Pane

You can view all variables for the current environment using the Railway CLI with railway variables and change the environment with railway environment.

Raw Editor

If you already have a .env file, or simply prefer to edit text, the Raw Editor can be used to edit variables in either .env or .json format.

Screenshot of Raw Editor

Variables can be defined as simple key/value pairs or as Templated Variables (eg. ${{Postgres.DATABASE_URL}}), which can dynamically reference other variables, shared variables, or plugin variables (more on this below).

Multiline Variables

Variables can span multiple lines. Press Control+Enter (cmd+Enter on Mac) in the variable value input field to add a newline, or simply type a newline in the Raw Editor.

Railway-Provided Variables

Railway provides the following additional system environment variables to all builds and deployments.

NameDescription
RAILWAY_STATIC_URLThe public domain, of the form example.up.railway.app
RAILWAY_SERVICE_{ServiceName}_URLThe public domain of a specific service within a project, of the form example.up.railway.app
RAILWAY_GIT_COMMIT_SHAThe git SHA of the commit that triggered the deployment. Example: d0beb8f5c55b36df7d674d55965a23b8d54ad69b
RAILWAY_GIT_AUTHORThe user of the commit that triggered the deployment. Example: gschier
RAILWAY_GIT_BRANCHThe branch that triggered the deployment. Example: main
RAILWAY_GIT_REPO_NAMEThe name of the repository that triggered the deployment. Example: myproject
RAILWAY_GIT_REPO_OWNERThe name of the repository owner that triggered the deployment. Example: mycompany
RAILWAY_GIT_COMMIT_MESSAGEThe message of the commit that triggered the deployment. Example: Fixed a few bugs
RAILWAY_HEALTHCHECK_TIMEOUT_SECThe timeout length (in seconds) of healthchecks. Example: 300
RAILWAY_ENVIRONMENTThe railway environment for the deployment. Example: production
RAILWAY_REPLICA_IDThe railway replica ID for the deployment. Example: 2

User-Provided Configuration Variables

Users can use the following environment variables to configure Railway's behaviour.

NameDescription
RAILWAY_DEPLOYMENT_OVERLAP_SECONDSHow long the old deploy will overlap with the newest one being deployed, its default value is 20. Example: 0
RAILWAY_DOCKERFILE_PATHThe path to the Dockerfile to be used by the service, its default value is Dockerfile. Example: Railway.dockerfile

Reference Variables

Variables can use the ${{VAR}} or ${{NAMESPACE.VAR}} syntax to reference other service variables, shared variables, or plugin variables.

The Railway dashboard provides an autocomplete dropdown in both the name and value fields to help create these references.

Screenshot of Variables Pane

Plugin Variables

Railway plugins offer a number variables that can be referenced by Railway services. To include a plugin variable, create a reference to the variable using the ${{<PLUGIN_NAME>.<VARIABLE_NAME>}} syntax.

NOTE: Railway's autocomplete will help create these references so you don't need to remember the exact syntax.

Shared Variables

Shared variables help reduce duplication of variables across multiple services within the same project. They are defined at the project environment level and can be added in Project Settings > Shared Variables.

Screenshot of Shared Variables Settings

To use a shared variable, either click the Share button and select the desired services, or visit the Variables tab within the service itself and click "Insert Shared Variable".

Screenshot of Shared Variables Picker

Under the hood, adding a shared variables to a service creates a new variable that references the shared variable using Railway's templating syntax (eg. NAME=${{shared.NAME}}). This means that shared variables can be combined with additional text or even other variables, like the following examples illustrate.

Import Variables from Heroku

You can import variables from an existing Heroku app using the command palette on the service variables page. After connecting your Heroku account you can select any of your Heroku apps and the config variables will be added to the current service and environment.

Screenshot of connect Heroku account modal

Service Discovery

On the Railway platform, services don't yet communicate via a Private Network. The team is working on: Private Networking. In the short term, you can reference other services via their public URL via a variable. You can use RAILWAY_SERVICE_{ServiceName}_URL to get the public URL of a service. For example, if you have a service named Backend API, you can reference it via RAILWAY_SERVICE_BACKEND_API_URL to get the public domain of the service.


Edit this file on GitHub