← Back to articles

Automating Custom Domains for Heroku Review Apps with Heracudo

Feb 13, 2025

Automating Custom Domains for Heroku Review Apps with Heracudo

Introduction

Deploying applications with Heroku Review Apps is a powerful way to test new features in an isolated environment. However, managing custom domains dynamically for each review application can be tedious. This is where Heracudo comes in—an npm package that automates domain creation in Cloudflare, updates Heroku configurations, and enhances GitHub pull request descriptions.

This article covers how to use Heracudo to streamline domain handling for Heroku Review Applications using Cloudflare and GitHub PRs.

Features

Heracudo automates the following tasks:

  • Custom Review App Domains: Generates subdomains dynamically in Cloudflare for Heroku Review Apps.
  • Heroku Configuration Updates: Automatically adds/removes domains in Heroku settings.
  • GitHub PR Integration: Updates pull request descriptions with preview links and status indicators.
  • Multiple Cloudflare Zone Support: Supports multiple HRCD_CLOUDFLARE_ZONE_ID values.

Installation

To install Heracudo in your Heroku Review Application, run:

npm i heracudo --save

Note: The package must be installed in dependencies, not devDependencies, to avoid being pruned after the Heroku installation process.

Configuration

1. Update app.json

Modify your app.json file to include the necessary deployment hooks:

{  "scripts": {    "postdeploy": "hrcd-postdeploy",    "pr-predestroy": "hrcd-predestroy"  }}

2. (Optional) Update package.json

For better tracking of review app statuses in GitHub PRs, you can add the following scripts to package.json:

{  "scripts": {    "postinstall": "hrcd-markpending",    "postbuild": "hrcd-markready"  }}

3. Set Environment Variables

You need to define the following environment variables in your Heroku pipeline settings or app.json:

Required Variables

HRCD_HOSTNAME Comma-separated list of base hostnames for review applications (e.g., domain.tld,sub.domain.tld).HRCD_HEROKU_TOKEN Heroku API access token.HRCD_CLOUDFLARE_ZONE_ID Comma-separated list of Cloudflare domain zone IDs, mapped to HRCD_HOSTNAME in order.HRCD_CLOUDFLARE_TOKEN Cloudflare API access token.HRCD_GITHUB_TOKEN GitHub API access token.HRCD_GITHUB_REPOSITORY GitHub repository in username/repository_name format.

Optional Variables

HRCD_GITHUB_LINK_MARKER Text before the preview link in GitHub PRs. HRCD_GITHUB_LINK_PENDING Text added when the review app is building. HRCD_GITHUB_LINK_READY Text added when the review app is ready.

Hooks Overview

Heracudo provides several lifecycle hooks for managing review applications:

hrcd-postdeploy: Runs when a review app is created. Adds domain to Heroku, creates a CNAME in Cloudflare, and updates the GitHub PR description.
hrcd-markpending: (optional) Marks the review app as pending in the GitHub PR when a rebuild starts.hrcd-markready (optional)Marks the review app as ready in the GitHub PR after deployment.
hrcd-predestroy: Runs when the review app is being deleted. Removes domains from Heroku, deletes Cloudflare CNAMEs, and cleans up the GitHub PR.

Example Workflow

  1. A developer opens a GitHub Pull Request.
  2. Heroku Review App is created, and Heracudo:
  3. Registers a subdomain in Cloudflare.
  4. Adds the domain to Heroku.
  5. Updates the GitHub PR description with a preview link.
  6. The developer commits more changes → Heroku rebuilds the app.
  7. hrcd-markpending updates the GitHub PR status as pending.
  8. Deployment completes → hrcd-markready marks the PR as ready 🚀.
  9. The PR is merged, and the review app is destroyed:
  10. The domain is removed from Heroku.
  11. The subdomain is deleted from Cloudflare.
  12. The GitHub PR description is cleaned up.

Enhancements in Custom Fork

Support for multiple HRCD_CLOUDFLARE_ZONE_IDs, mapped to multiple hostnames.

This enhancement allows you to manage multiple Cloudflare zones dynamically, making domain management more flexible for complex applications.

🔗 GitHub Repo: Ceda/heracudo

Conclusion

With Heracudo, managing custom domains for Heroku Review Applications becomes effortless. It integrates Cloudflare, GitHub, and Heroku to ensure each review app gets a unique, automatically configured domain with live PR updates.

By leveraging the multi-zone support from your custom fork, you can now handle multiple domain zones, making Heracudo even more powerful.

🚀 Start using Heracudo today and automate your Heroku Review App domains!

Latest articles