Environment variables

Last updated on 28th October 2025

Variables in a DeployHQ project are dynamic elements based on various aspects of a deployment that can be used specifically in Config files, SSH commands and in most cases, notifications. You'll find a full list of these variables by clicking the link below your main configuration box when you're configuring either feature.

A useful example is the %environment% variable that can be added in your server's settings when you're configuring it. You might add the %environment% variable several times in a config file to match some preconfigured environment variables on the end server, such as ENV['%environment%'].

Custom Environment Variables

Beta Feature: Custom Environment Variables is currently in beta. To access this feature, beta features must be enabled for your account.

In addition to the built-in variables listed below, you can create custom environment variables for your project. These are user-defined variables that can store sensitive data like API keys, database credentials, or any other configuration values you need during deployment.

Creating Environment Variables

To create a custom environment variable:

  1. Navigate to your project and click on "Environment Variables" in the sidebar
  2. Click "New Environment Variable"
  3. Enter a variable name (must start with a letter and contain only uppercase letters, numbers, and underscores)
  4. Enter the value for the variable
  5. Choose whether to use this variable in the Build Pipeline
  6. Select which servers or server groups should have access to this variable

Environment variables

Features

Encryption: All variable values are encrypted at rest for security. The encrypted values are never visible in logs or the user interface.

Locking: You can lock a variable to make it immutable. Once locked, the value cannot be viewed or changed, providing an extra layer of security for sensitive credentials. Locked variables continue to work in deployments.

Build Pipeline: By default, variables are available in both Build Pipeline commands and server deployments. If you uncheck "Use this variable with the Build Pipeline", the variable will only be available during deployments to servers.

Server Targeting: You can make variables available to: - All current and future servers - Specific server groups - Individual servers

Variable Precedence

When the same variable name is defined multiple times with different server targeting, DeployHQ uses the following precedence order (highest to lowest):

  1. Server-specific: Variables assigned to an individual server
  2. Server group: Variables assigned to a server group
  3. All servers: Variables available to all current and future servers

For example, if you have a DATABASE_URL variable set for "all servers" with value postgres://default, but also set it specifically for your production server with value postgres://production, the production server will use postgres://production while other servers use postgres://default.

This precedence system allows you to define sensible defaults while overriding specific values where needed.

Using Custom Variables

Custom environment variables use the same syntax as built-in variables. Reference them in your Config files, SSH commands, or Build Pipeline commands using %VARIABLE_NAME%.

For example, if you create a variable named API_KEY with value abc123, you can reference it as %API_KEY% and it will be replaced with abc123 during deployment.

Built-in Variables

The following variables are automatically provided by DeployHQ during deployments:

These variables refer to the project

  • %startrev% - Start revision commit ref
  • %endrev% - End revision commit ref
  • %startrevmsg% - Start revision commit message
  • %endrevmsg% - End revision commit message
  • %tag% - Tag related to end revision (if present)
  • %branch% - The branch of the deployment
  • %count% - This number of deployments in the project
  • %servers% - Names of the servers in this deployment
  • %deployer% - User who started the deployment (if manually deployed)
  • %commitrange% - The start and end commit, separated with a hyphen
  • %project% - The name of this project in deploy
  • %projecturl% - The address of this project in DeployHQ
  • %projectperma% - The permalink of this project in DeployHQ
  • %deploymenturl% - The address of this deployment in DeployHQ
  • %status% - The current status of this deployment

These variables can be used for a server group, or an individual server:

  • %environment% - Server or server group environment (development, production etc.) - the server group environment setting will take precedence over that on any individual servers within the group.

These variables refer to a specific server (therefore, incompatible with server groups)

  • %username% - Username used to login to the server
  • %password% - Password used to login to the server
  • %groupindex% - The order within it's group that this server is deployed (zero-indexed)
  • %path% - Base server path we’re deploying to

These variables can be used on a server configured for zero-downtime deployments

  • %release_path% - Path that the release is being deployed to
  • %shared_path% - Path containing shared files that will be symlinked to release
  • %current_path% - Symlink pointing to the currently active release
  • %previous_release_path% - Path to the previous release

These variables can be used on a all servers

  • %release_path% - Path that the release is being deployed to