Last updated on 6th March 2026

Deploying linked projects

If you have two separate projects in DeployHQ that are linked -- for example, a backend API and a frontend application in different repositories -- you may want to automatically deploy the second project whenever the first one completes. This guide explains how to set that up using the HTTP integration and the DeployHQ API.

Use case

A common scenario is:

  • Project A (e.g. a backend API) deploys to Server X
  • When that deployment completes, Project B (e.g. a frontend app) should automatically deploy to Server Y

Since the two projects use different repositories, they are managed as separate DeployHQ projects. However, you need them to deploy in sequence so that the latest versions of both applications are always running together.

How it works

  1. Project A deploys as normal (manually or via automatic deployment)
  2. An HTTP integration on Project A fires when the deployment completes
  3. The integration calls the DeployHQ API to create a new deployment on Project B, targeting the specific server you choose
  4. Project B deploys to the specified server

Step 1: Find Server Y's identifier

You will need the UUID of the server in Project B that you want to deploy to.

Using the API

You can retrieve the server list for Project B using the Servers API:

curl -H "Content-type: application/json" \
  -H "Accept: application/json" \
  --user your-email@example.com:your-api-key \
  https://your-account.deployhq.com/api/v1/projects/project-b-permalink/servers

Each server in the response will include an identifier field (UUID). Copy the identifier for Server Y.

Using the DeployHQ interface

Alternatively, navigate to Project B > Servers > Server Y in the DeployHQ interface and look for the server's UUID in the URL or server settings.

Step 2: Set up the HTTP integration on Project A

  1. In Project A, navigate to Integrations on the left-hand side
  2. Click New Integration
  3. Select HTTP from the service picker
  4. Configure the integration as follows:

URL

https://your-account.deployhq.com/api/v1/projects/project-b-permalink/deployments

Replace your-account with your DeployHQ account subdomain, and project-b-permalink with the permalink of Project B.

Authentication

Select Basic authentication and enter your DeployHQ login email and API key. You can find your API key in your DeployHQ account settings.

Payload

Select Custom and enter the following JSON body:

{
  "deployment": {
    "parent_identifier": "SERVER-Y-UUID-HERE",
    "start_revision": "latest",
    "end_revision": "latest",
    "mode": "queue",
    "copy_config_files": true,
    "run_build_commands": true
  }
}

Replace SERVER-Y-UUID-HERE with the UUID you found in Step 1.

Trigger settings

  • Set the integration to trigger When deployment completes
  • If Project A has multiple servers, select Server X specifically so the integration only fires when Server X is deployed (rather than triggering for every server)

Click Create Integration to save.

Step 3: Test the setup

  1. Run a deployment on Project A to Server X
  2. Once it completes, check Project B -- you should see a new deployment queued or running for Server Y
  3. Verify both applications are running the correct versions

Alternative: Trigger both deployments from CI/CD

If you want both projects to deploy simultaneously rather than in sequence, you can trigger both deployments from your CI/CD pipeline (e.g. GitHub Actions) using the DeployHQ API. This approach is better when the two projects do not depend on each other's deployment completing first.

Example using curl in a CI script:

# Deploy Project A to Server X
curl -X POST \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  --user your-email@example.com:your-api-key \
  -d '{"deployment":{"parent_identifier":"SERVER-X-UUID","start_revision":"latest","end_revision":"latest","mode":"queue"}}' \
  https://your-account.deployhq.com/api/v1/projects/project-a/deployments

# Deploy Project B to Server Y
curl -X POST \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  --user your-email@example.com:your-api-key \
  -d '{"deployment":{"parent_identifier":"SERVER-Y-UUID","start_revision":"latest","end_revision":"latest","mode":"queue"}}' \
  https://your-account.deployhq.com/api/v1/projects/project-b/deployments

Things to keep in mind

  • Deployment failures: If Project A's deployment fails, the HTTP integration will not fire (assuming you set the trigger to "When deployment completes"), so Project B will not be deployed. This is usually the desired behaviour.
  • Branch configuration: The API deployment will use the branch configured on Server Y by default. You can override this by adding a "branch" field to the payload.
  • Build commands and config files: Adjust the copy_config_files and run_build_commands options in the payload based on your Project B server configuration.
  • API authentication: We recommend creating a dedicated API key for this integration rather than using a personal account's credentials.
  • Rate limits: Each deployment will count towards your account's deployment limits.