Last updated on 2nd April 2026

Global Config Files

Global config files are account-level file templates that you can reuse across multiple projects in DeployHQ. Instead of creating the same config file in every project, you can define it once at the account level and then link it to any project that needs it. Changes to the global config file automatically apply to all linked projects.

Creating a global config file

To create a global config file, go to your DeployHQ account settings by clicking on "Settings" in the top bar, then click on "Global Config Files" in the left column. Click "New Global Config File" to begin.

Configure the config file with the following options:

  • Path -- The file path relative to the deployment root (e.g., config/database.yml).
  • Body -- The contents of the file. You can include variable placeholders using %VARIABLE_NAME% syntax.
  • Description -- An optional description to help identify the purpose of the config file.
  • Build -- Whether the config file should be available during the build pipeline.

Variable placeholders

Global config files support variable placeholders using the %VARIABLE_NAME% syntax. These placeholders are resolved during deployment using the project's environment variables. For example:

production:
  adapter: mysql2
  host: %DB_HOST%
  database: %DB_NAME%
  username: %DB_USER%
  password: %DB_PASSWORD%

When the config file is deployed, each %VARIABLE% placeholder is replaced with the corresponding environment variable value defined in the project.

Linking to a project

To add a global config file to a project, navigate to the project's Config Files page and click "Add Global Config File". A dialog will show all available global config files. Click "Add" to link one to the project.

When a global config file is linked to a project:

  • The file content is managed at the account level. Editing the global config file automatically updates all linked projects.
  • You can override the file path per project if needed (e.g., deploy the same template to a different location).
  • You can choose which servers or server groups the file should be deployed to within each project.
  • Global config files appear in the project's config files list with a "Global" badge.

To remove a global config file from a project, click the remove button next to it in the project's config files list, or use the "Remove" button in the "Add Global Config File" dialog.

Build pipeline

The Build option controls whether the config file is placed into the build environment before build commands run. This is useful for configuration files that your build process depends on, such as:

  • Database configuration files needed for asset compilation
  • Environment-specific settings files
  • Build tool configuration

If the build option is disabled, the config file is only deployed to servers during the deployment step.