Last updated 09 July 2020

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:

If you already have review apps enabled, click Upgrade in your pipeline’s Settings tab. Any pre-existing review apps will be automatically moved to the new version:

You can also upgrade to the new Review Apps from under the REVIEW APPS column of the pipeline:

Selecting the URL pattern

Once review apps are enabled, or the upgrade from the older version is complete, visit the pipeline’s setting tab to check and update the URL pattern of your review apps. The default is set to random but selecting the “Update URL pattern” option will open a side panel where you can change from random to 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 new version of review apps supports 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:hobby-dev"]
    }
}

Review app names

This new version of 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.

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.

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 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 new 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.

Feature Changes

Here’s a summary of the changes that have occurred between this new version of Review Apps, and the previous:

• Review apps now has a public facing API.
• The app names generated by review apps can be random or predictable. User have a choice depending on their environment and use cases.
• Pull requests are no longer required
• The new version of review apps does not support parent apps - inherited configuration is specified in app.json or in the Pipeline’s configuration variables. Use the new pipeline access tab to configure permissions and user access that was previously handled by the parent app.
• Review apps can be enabled in multiple pipelines for the same repository
• Review Apps (and CI Apps) permissions can now be easily managed via a new pipeline access tab

The API lets you automate complex workflows, and lets you easily integrate with other CI tools or testing applications. It makes it possible to have multiple pipelines coordinated, or to build a dashboard for other users and teams so they can see the status of different branches without giving them Heroku access. Removing the need to have GitHub pull requests makes it possible for users that don’t use GitHub, to utilise Review Apps and automate their development flow, or simply spin up new instances for demo purposes.

Permission Changes

There have also been changes to the permission model:

• 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.