Last updated August 22, 2023

Review apps run the code in any GitHub pull request in a complete, disposable Heroku app. Review Apps each have a unique URL you can share, making them a great way to propose, test, and merge changes to your code base.

You can configure review apps to spin up automatically for each pull request, or you can create them manually from your app’s Pipeline page in the Heroku Dashboard. Note that your app must enable both Heroku Pipelines and GitHub integration to use review apps.

Setup

Prerequisites

• An existing pipeline. Learn more about pipelines and creating one here.
• An existing repo on GitHub.com with your application source code.

Getting Started

If you are new to review apps, navigate to your pipeline’s Settings tab in the Heroku Dashboard. On that page, connect your pipeline to the corresponding GitHub repository.

You may need to also configure an app.json if you have not used Review Apps before. See the configuration section and the app.json Schema for further details. For any secret config var values that you do not wish to add to your app.json, set them as review app config variables in the pipeline’s settings.

After configuring the app.json, first-time review app users can select the Enable Review Apps option from either under the Settings tab of the Pipeline tab or the Review Apps column of the Pipeline:

Selecting the URL pattern

After enabling Review Apps, visit the pipeline’s Settings tab to check and update the URL pattern. The default is set to random but click Update URL pattern to open a side panel with options for random or predictable naming.

Setting up permissions

You can manage access to all review apps and CI apps within a pipeline via the pipeline access tab. To learn more about pipeline-level permissions please see ephemeral app permissions in pipelines.

Creating review apps

When creating a review app, Heroku deploys the HEAD commit of the branch that the associated pull request is based on. Whenever the branch is updated, Heroku deploys the latest commit to the review app.

Manual creation

Your app’s Pipeline page displays your connected GitHub repo’s open pull requests. You can manually create review apps for a listed pull request by clicking the Create button next to it.

Automatic creation

With automatic creation, Heroku creates a review app as soon as a pull request is opened on your app’s connected GitHub repo. For security and billing reasons, Heroku does not automatically create review apps for pull requests to public repos that are sent from forks. You can still create review apps for these pull requests manually.

Viewing review apps

When a review app is created, a link to open it in your browser is available from GitHub (in the pull request’s Conversation tab):

This link is also available in the Heroku Dashboard (in the Review Apps column of your app’s Pipeline page):

You can view, manage, and inspect a review app just like you would any other Heroku app. You can view a details of its deployment status by clicking the View initial app setup and View latest build links.

Configuration

An app.json file is required in the root of your app’s GitHub repo for review apps to work. The app.json file is used to configure new apps created when pull requests are opened.

An add-on provider may specify a default ephemeral plan that overrides any plan choices you’ve made. If an add-on provider has specified an ephemeral default plan, new instances of each add-on specified in your app.json will be provisioned using it. This provides a fast, inexpensive set of dependencies to test pull requests while allowing add-on partners to constraint provisioning costs.

Sensitive config vars

Set any sensitive environment variables in the Review app config vars section of your pipeline’s settings. All review app config vars from the pipeline settings will be injected into the review app when it is created, regardless of whether or not it is included in the app.json.

Environments in app.json

Similar to the behavior in Heroku CI, the Review Apps support the “environments” key. For configuration specific to review apps, you may use the environments.review key. For instance, if you want to use a different database plan for review apps, you could use a configuration like below. Anything nested inside the environments.review key will be merged into the base configuration.

{
  "addons": ["heroku-postgresql:standard-0"],
  "environments": {
    "review": {
      "addons": ["heroku-postgresql:mini"]
      }
  }
}

Review app names

Review Apps uses some randomness to prevent naming collisions. Instead of inferring details about the app with HEROKU_APP_NAME and regular expressions, we suggest using the automatically injected environment variables instead.

The postdeploy script

The app.json file has a scripts section that lets you specify a postdeploy command. Use this to run any one-time setup tasks that make the app, and any databases, ready and useful for testing. Postdeploy is handy for one-off tasks, such as:

• Setting up OAuth clients and DNS
• Loading seed/test data into the review app’s test database

For a Ruby-on-Rails app, your postdeploy command might be:

bundle exec rake db:schema:load db:seed

In this case, the db/seeds.rb file should seed the database with comprehensive data so that the review apps can be used for testing without further setup.

Postdeploy is run only once after the app has been created

Note that postdeploy is run only once, after the app has been created and deployed for the first time. It is not run when subsequent changes are deployed. To re-run a review app’s postdeploy script, you have to close and re-open the pull request. This causes Heroku to destroy and re-create the review app.

Use release phase to run commands with each change to a pull request

To run commands with each change to a pull request, use release phase. Release phase is useful for tasks such as, uploading assets to a CDN, invalidating or priming cache stores, and running database schema setup and migrations. Release phase is run before the postdeploy script.

pr-predestroy script

You can optionally specify a pr-predestroy script on your app.json file. This script runs when review apps are destroyed once the associated pull request is merged or closed.

{
  "name":"Node.js Sample",
  "scripts": {
    "postdeploy": "bin/bootstrap",
    "pr-predestroy": "bin/teardown"
  }
}

Use the pr-predestroy script to tear down any resources provisioned during postdeploy and to do other clean-up.

Apps using Docker images can’t use pr-predestroy scripts. These scripts get ignored if included in your app.json file.

Injected environment variables

The following environment variables are added to each review app when it is created:

• HEROKU_APP_NAME: The name of the review app
• HEROKU_BRANCH: The name of the remote branch the review app is tracking
• HEROKU_PR_NUMBER: The GitHub Pull Request number if the review app is created automatically

To help with scripting, two special config vars are available to review apps. They are available to all Review Apps and there is no need to specify them in the app.json file.

Disabling review apps

You can disable review apps at any time. Doing so prevents new review apps from being created.

Heroku Postgres Extensions

Starting July 10, 2023, new review apps that provision Heroku Postgres databases, such as an Essential-tier database, install extensions in the public schema by default. If your application expects extensions in the default heroku_ext schema, then errors can occur.

You can define a schema for extensions with CREATE EXTENSION…WITH SCHEMA…. For example, to have your review apps install extensions in the heroku_ext schema, use the following in your database setup scripts:

CREATE EXTENSION extension_name WITH SCHEMA heroku_ext

Review apps and CI

If you have Heroku CI enabled for your pipeline, note that all subsequent commits to the pull request will run your tests against the review app’s updated build. Test results are available as usual in the pipeline’s Tests tab. The updated code will be built and deployed even if tests fail (because pull requests are experimental by nature, Heroku does not block deployment to review apps).

The above conventions are also true for other CI systems you integrate with Heroku Pipelines.

Review apps and Heroku Private Spaces

Private Spaces are dedicated environments for running dynos and certain types of add-ons enclosed within an isolated network. Apps that reside in private spaces can occupy any stage in a pipeline.

Review apps can spawn and run in any Private Spaces as long as the region or space is specified as part of the apps’s configuration in the app.json file. Example:

{
 "app": { "region": "us" }
}

{
 "app": { "space": "1234-abcd" }
}

Review apps and Docker

If you want to use a Dockerfile to define your build, you need to include a heroku.yml file in your project. With heroku.yml, Heroku builds the Docker image(s) that you specify and uses them in your review apps (an app.json file is still required).

Review apps management and costs

Dynos and add-ons used by review apps are charged in exactly the same way as for normal apps. Costs are pro-rated to the second, and you’re only charged for the time that the review app exists.

In most cases, Heroku defaults to using the least expensive dyno available in your plan for review apps. However, apps in Private Spaces default to using private-m dynos. You can specify a different dyno size in your app.json file.

Review apps exist only for the life of their associated pull request, and can be set to be destroyed automatically after 1, 2, 5, 14 or 30 days of inactivity:

You can optionally specify free or low-cost add-on plans in your app.json if those plans are sufficient to run and test your app. Because review apps are typically short-lived, and you are charged only while they exist, monthly charges are typically small.

For review apps that are automatically created, any costs are incurred by the user who connected the app to GitHub. When review apps are manually created, the cost is incurred by the user who created the review app.

See the Usage and Billing article for details.

Review apps API

The Review Apps API is an extension of the Heroku’s Platform API. It allows you to enable, disable, create, and delete review apps. See the API documentation for more details, in particular the sections for review apps, review app configuration, and config vars.

Permission Changes

In addition to Pipeline permissions and capabilities, review apps also have the following permission model changes:

• All Heroku Team and Enterprise Team users with “admin” role have full access to all Review Apps and CI Apps within the team.
• All Heroku Team and Enterprise Team users with “member” role have the “View”, “Deploy” and “Operate” permissions on all Review Apps and CI Apps inside the team. This does not enable these users to promote the application though.
• If a user creates a pull request in Github, they will only be able to see the review app generated for that pull request in Heroku if their Heroku account has access to the application. Having the permission to create a pull request in the Github repo does not guarantee access to the review app.
• Review Apps will be built for new commits even if the user making changes and commits on GitHub doesn’t have access to the Heroku app.
• We use the token of the user who links the Pipeline to Github for creating Review Apps.
• Users with “Collaborator” permission on an app within a Pipeline can not access Review Apps automatically. To give collaborators access to Review Apps and CI Apps, please add them to the new permission table in the pipeline’s access tab.

FAQ

Do git submodules work?

No, GitHub repos that use submodules will generally not deploy correctly on Heroku. This is because GitHub does not include submodule contents when repo-content tarballs are generated.

Fourchette and review apps

The idea of creating Heroku apps for pull requests created on GitHub was pioneered by Rainforest with Fourchette.