Chapter 4

Advanced configuration

Set up more advanced options in your project

Config Files

Config files in DeployHQ are files that you want to upload during a deployment, but not keep in your repository. This is particularly useful for configuration files that might contain sensitive data such as a database config file.

To add a config file, head to your project's Settings dropdown, then the Config Files option. Click to add a new config file, entering the full path to it as the name, then any data you need it to contain.

Config files

If you wish to deploy the file to certain environments, uncheck the Upload this file to all current and future servers? option and you'll be able to choose specific servers that have been configured in your project. As a result, you can set up multiple configuration files for each environment type (development, staging, production etc) and only deploy them where you need to.

Upload to a specific server

Excluded Files

Excluded files in DeployHQ are files that you need to store in your repository, but not upload to your server. This might be useful for certain assets within your app that you want to version control but not actually deploy.

To add an excluded file, head to your project's Settings dropdown, then the Excluded Files option. Click to add a new excluded file, entering the full path as the name, or one of the standard recipes if you want to exclude directories or specific file types.

Excluded Files

If you want to exclude files for certain server environments in your project, uncheck the Exclude this file on all current and future servers? option and select individual servers.

Excluded on a specific server

Common Recipies

Some working examples of file exclusion rules might look like so:

  • vendor/** — All files and subdirectories within your vendor directory will be excluded from deployments
  • **/*.yml — Any yml files will be excluded from deployments
  • config/*.php — All PHP files, only within your config directory will be excluded from deployments


As well as adding excluded file rules in DeployHQ, you can add a .deployignore file to your repository containing rules in the exactly the same format and store it in your repository. Just add each rule on a new line, then DeployHQ will check this file and exclude any files or directories from the deployment as appropriate.

DeployHQ doesn't have support for specifying specific servers in .deployignore, therefore if you need to configure rules for certain servers, you'll need to use the Excluded Files feature in the DeployHQ interface.

SSH commands

SSH commands are commands that you can configure to run on a server before or after a deployment. These can be anything your server supports, such as starting or stopping services related to your app, or running a database migration.

To configure an SSH Command, head to the SSH Commands on the left hand side of the page within your project, then click New SSH Commmand to start:

Config files

Enter a descirption for your command which will be displayed in the deployment log, then the exact command you want to execute below. If you're executing multiple commands on different lines, you may need to terminate each line with a \.

Next, you can choose how long the command can run for, and the option to stop the deployment completely if the command fails, which may be particularly useful if you're running commands before the file upload process is started.

After that, choose when the command should be executed; before or after the file upload process, then for all deployments, the first deployment, or every deployment after the first one.

Finally, you can choose if you want the SSH command to run on all servers in your project, or for only specific ones. If you want to set specific servers, first uncheck the Run this command on all current and future servers? option then you'll be able to select individual servers in the Choose a server dropdown.

Specific server

Advanced server configuration

When configuring a server to your project, you can configure a number of useful Deployment Options:

Deployment options

Branch to deploy from

You can choose any branch in your repository to monitor for changes and run deployments from.


Add any value you like here that can be used in Variables for substitution into SSH commands or config files. Just use a simple string such as Development, Testing or Production. This might be useful if you're using multiple servers in your project with different environments such as a development and production server so that you can differentiate between the two.

Subdirectory to deploy from

If you want to deploy only a certain directory in your repository, you can choose that option here. You'll need to enter the directory as a relative path starting from the root of the repository itself, for example app, if you wanted to deploy only files contained within your app directory.


Variables in a DeployHQ project are different elements based on various aspects of a deployment that can be used specifically in Config files, or SSH commands. 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%'].

Scheduling deployments

When running a deployment for a given server or server group, rather than deploying straight away you can set a schedule for the deployment, either to run once in the future or for a regular set period.

Within the main deployment screen you'll see an option at the bottom of the page - Schedule Deployment.

Schedule Deployment

The default option is set to Start immediately, with additional options displayed below.

Run in the Future

Selecting the option to Run in the future will provide a selectable date and time to schedule your deployment for.

Run in the future

Run Daily

Selecting to Run Daily will present a single time option that you can set for DeployHQ to run a deployment every day.

Run daily

Run Weekly

Run Weekly will show a day and time option, so that you can choose certain day of the week and a time of day to schedule this deployment to run at.

Run weekly

Run Monthly

The option Run Monthly will bring up a single day and a time to schedule your deployment for.

Run monthly

In each case you'll be able to select the option to Always deploy from the last deployed commit to the latest avaialble commit which will ensure you always deploy the changes between your last deployment and the last commit pushed when the scheduled deployment starts. Otherwise, it will deploy the commits set when you first scheduled the deployment.

Once you've set your desired schedule, just click the Deploy button to set it.

You'll now see your scheduled deployment within your overview, below the last deployment for the particular server or group that it has been set up for, with a time remaining until the next deployment displayed if it has been set to run on a regular schedule.

Scheduled deployment

If you need to remove this or any other schedule, simply click the delete icon next to it in your list.

Rolling back a deployment

You may find that you wish to rollback to a previous commit set when deploying to your server. Just navigate to the deployments page with your project, then select a server by clicking its name to view a list of deployments for it.

Deployments list

Click View to the right hand side of the the deployment before your latest one in the list:


Now within the deployment details you will see an option to Rollback to this deployment at the bottom. Once that is clicked, the appropriate commit references will be reversed, and a new deployment page will load:


If you are happy with the information displayed, you can click Deploy to start the rollback. Alternatively if you wish to preview the rollback just click the appropriate button.

When the rollback has finished, you'll find that all changes in the latest deployment are reversed. If you've added new files in that deployment they'll be removed, any deleted files will be restored, and modified files will see their previous versions uploaded.

Deploying from scratch

If you have a requirement to deploy your entire repository to a server, such as in the case of changing hosts, you can do so simply by clicking the orange commit selection icon next the start commit reference when running a new deployment, checking the option to Deploy the entire repository, then Choose Revision.

Deploy the entire repository

You will now see The very first commit… in the start commit entry, so just click Deploy to finish, or Preview if you wish to run a preview of the deployment first.

Don't deploy from scratch on your first deployment

When you create a new server in DeployHQ, by default the whole repository will be uploaded to your server. This is great when you're starting afresh, but not useful if your files are already present on the server.

For example, the latest commit in your repository is 67d0f651 and the files up to reference 67d0f651 are already on your server, and you want to create a new server in DeployHQ but you don’t want it to re-deploy all the files that already exist on your server.

You can skip this by simply by clicking the orange commit selection icon next the start commit reference when running the first deployment, choosing the commit at the top of the list then clicking Select Commit.

Skip deploying from scratch

Both revisions will now be set as the same reference, and your deployment will run without uploading any files. Then, any deployments after this will just deploy the changes pushed as normal.

Updating the repository in an existing project

Whilst adding a repository alongside a new project is easy with the OAuth method, you may wish to update an existing project's repository settings rather than create a new project, especially if you wish to keep the previous deployment history.

Updating the repository URL

Firstly, you'll need to navigate to the Configuration link below Repository on the left hand side of your project, then change the Full repository URL.

Repository URL

Where you're connecting via SSH as in most cases, you'll need to upload the project's public key to your new repository. You'll find this directly below the repository URL.

You can find information about how to upload the public key to our main supported hosts below:

Otherwise, if you're connecting via HTTP, just update your username and password, if appropriate. Click Update Repository, then DeployHQ will recache it from the new location.

Adding a deployment key to Bitbucket manually

To add a new Deployment Key to Bitbucket, navigate firstly to your repository's Settings via the link near the bottom of the sidebar, then to the Access Keys page:

Bitbucket settings

Then click the Add Key button:

New key

Now give your new key a description, paste the key in, and click Add Key to finish.

Add key

Adding a deployment key to Codebase manually

To add a new Deployment Key in Codebase, first navigate to your repository's Settings to the right hand side of the browser:


Now go to the Deployment Keys tab, and click Add new SSH public key. Now enter a name for your new key, paste the key into the Public Key field, then click Add Public Key to save it.

New key in Codebase

Adding a deployment key to Github manually

To add a new deployment key to your Github repository, go to the Settings tab above your repository browser, then Deploy Keys on the left hand side. Next click the Add deploy key button above the list of keys.

Give your new key a name, paste the key from DeployHQ into the Key field, then click Add Key to save it.

Github key

Adding a deployment key to Gitlab manually

To add a new deployment key in Gitlab, start by navigating to your Settings tab at the top your project, then Repository just below:

Gitlab keys

You'll find an option to add a new deployment key at the top; give the key a name, paste in your public key into the Key field, then click Add Key to save it.

New Gitlab key

Running a new deployment from the updated repository

Now you've updated the repository, you'll need to ensure you deploy from the correct commits. In particular, if the last deployed commit to any servers in your project doesn't exist in the new repository.

Just click the orange commit selector icon to the left of the start commit, then either choose a previous commit found in your new repository, or the option to Deploy the entire repository at the bottom.

Commit chooser

How do I recache a repository?

Whenever you tell us about one of your repositories, we have to store a copy of it on our servers. This allows us to quickly access your commit history and files whenever you wish to deploy the project.

If you change your repository’s URL for example, we’ll need to re-download it and we'll recache it automatically, but if you need to tell DeployHQ to recache your repository, you can do so yourself at any time.

Just head to the Configuration page via the link on the left hand side in your project, then click the Recache Repository button at the top of the screen.


How do I upload my own custom private key?

In DeployHQ, you can upload your own custom keypair to one or more projects. This might be useful if you have a number of different projects all deploying to the same servers.

To upload a new key pair, head to the Configuration page in any project, then below the current public key you'll find a link to upload a private key. Click this link, then upload your the private key by pasting it in the dialog, then clicking Upload Private Key;

New private key

Uploading a custom private key will cause it to be used for all servers and repositories in that project, therefore you may be required to update the public keys on these services to reflect the new keypair if you're using SSH authentication with them.

Deleting a project

To delete a project in DeployHQ, navigate to the Settings page via the link on the left hand side, then the Delete Project button at the bottom of the page.

Delete a project