Review Apps

Last updated 09 August 2018

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.

Setup

You enable review apps from your app’s Pipeline page in the Heroku Dashboard by clicking Enable Review Apps.

If your GitHub repo’s master branch doesn’t include a required app.json file in the root directory, the following dialog appears:

Choose a “parent” app in your pipeline that’s connected to the correct GitHub repo and click Create an app.json File.

This opens a form that helps you fill out the initial version of your app.json file. If you’re not sure what values to specify in the form, you can simply click Commit to Repo to commit a skeleton app.json file that you can fill in later.

After you click Commit to Repo (or if your app already included an app.json file), the following dialog appears:

This lets you specify:

• The app that your review apps inherit their configuration from
• Whether review apps should spin up automatically for new pull requests
• Whether stale review apps should be deleted after a period of inactivity

Click Enable to complete the setup.

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. When the pull request is closed, Heroku destroys 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.

The app.json file

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.

New instances of each add-on specified in your app.json are provisioned using the ephemeral default plan specified by the provider. This provides a fast, inexpensive set of dependencies to test pull requests.

Inheriting config vars

Review apps can “inherit” config vars from their parent app without requiring the values be committed to source in the app.json file. This is convenient for credentials that you don’t want in source control, but that are required for the code to deploy and run (like API_KEY for provisioning OAuth clients or an AWS key for S3 storage).

To create an app.json file that lets you use value inheritance, you can either use the Dashboard app.json generator (which will inherit from master app by default) or specify inheritance yourself. Entries that do not have a value will be copied from the env of parent apps to review apps. For example:

 "env": {
    "INHERIT_THIS_CONFIG_VAR": {
      "required": true
    },
    "DONT_INHERIT_THIS_CONFIG_VAR": "production"
  },

The inherited config is available when the postdeploy script specified in app.json is run after review apps are created, so you can provision OAuth clients and do other set-up tasks at that time.

Both required and non-required config vars can be inherited.

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.

HEROKU_APP_NAME and HEROKU_PARENT_APP_NAME

To help with scripting, two special config vars are available to review apps. If you specify HEROKU_APP_NAME or HEROKU_PARENT_APP_NAME as required or optional config vars in your app.json file, Heroku will set those config vars to the new application name and the parent application name respectively. They will then be available for use in the postdeploy script so that you can do more advanced bootstrapping and configuration.

Here is an example app.json file that uses HEROKU_APP_NAME and HEROKU_PARENT_APP_NAME:

{
  "name":"Advanced App",
  "scripts":{
    "postdeploy":"rake db:setup && bin/bootstrap"
  },
  "env":{
    "HEROKU_APP_NAME": {
      "required": true
    },
    "HEROKU_PARENT_APP_NAME": {
      "required": true
    }
  }
}

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 whose parent resides in a Private Space can spawn and run either in that same Private Space (for containment and compliance purposes) or in the Heroku Common Runtime (for cost savings).

When you set up review apps, these additional options appear if the parent app resides in a Private Space:

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

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.