Review Apps

Last updated 31 August 2016

Review apps run the code in any GitHub pull request in a complete, disposable app environment on Heroku. Each review app has a unique URL you can share.

You can configure review apps to spin up automatically for each pull request, or create each manually at the push of a button from the Heroku Pipelines page of the connected repo.

Either way, the URL for your review app is available on creation – in GitHub (in the deploy message area), or in Heroku (in the “review apps” column of the Pipelines page for the repo).

Review apps are a great way to propose, discuss and merge changes to your code base. Because pull request branches are deployed to new apps on Heroku, it’s very simple for you and your collaborators to test and debug code branches. You can also run automated integration tests on the Heroku app representing a GitHub branch.

Review apps

Review apps can only be used conjunction with Heroku Pipelines. Review apps are spun up from pull requests on an app occupying a stage in the pipeline.

When you enable review apps for an app that is connected to a GitHub repo, Heroku will display the currently open GitHub pull requests on the repo. You can manually create Heroku review apps for each of the open PRs by clicking the “Create” button next to the pull request that will appear on the Pipeline’s main page.

Alternatively, you can enable automatic review app creation. That will cause Heroku to create and deploy apps as soon as pull requests are opened on GitHub. For security and billing reasons, Heroku will not automatically create review apps for pull requests to public repos that are sent from forks. Review apps can still be created manually for these pull requests.

Once an review app has been created for a given PR, you can run it in a browser (at the review app URL), manage it, and inspect logs just like you would any other Heroku app. You can also view a summary of the deployment status for the review app by clicking the “View log” link. Tool tips fly-overs explain the icons in the review apps column of the Pipelines page, which provide useful information and links on billing, ownership, and authorship.

Heroku will deploy the HEAD commit of the branch that the pull request is based on. Whenever the branch is updated, Heroku will deploy the latest commit. When the pull request is closed, Heroku will destroy the review app that was linked to the pull request.

When Heroku deploys to review apps, a deployment notification is posted to the GitHub pull request. Collaborators on GitHub can follow the link in the notification to inspect and test the app on Heroku.

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 Heroku Pipeline.

Review apps whose parent resides in a Private Space can spawn and run in that Private Space (typically for containment and compliance) or in the Heroku Common Runtime (typically for cost savings).

When Review apps are configured, these additional options will appear if the parent app resides in a Private Space

app.json

An app.json file is required in the root of the 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 add-ons specified in app.json will be added to review apps created by Heroku. This will let you test PRs with a fresh set of dependencies.

If you configure review apps on an app synced to a repo that doesn’t have an app.json file, Heroku will help you generate one. You can either add, commit and push the generated app.json yourself, or Heroku can push it to GitHub for you.

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 AWS key for S3 storage).

To create an app.json file that lets you take advantage of 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.

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.

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

In addition to seeding databases, you can also do other one-time setup for newly created apps with the postdeploy command.

pr-predestroy script

You can optionally specify a pr-predestroy script on your app.json file. This is run 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 may disable review apps at any time. Doing so will prevent new review apps from being created.

Review apps management and costs

Review apps are charged as any other app you might create. By default, Heroku uses the least expensive dyno available in your plan for each review app. Review apps exist only for the life of the associated pull request, and can be set to self-destruct after 5 days of inactivity. Because you are charged only when the review app is actually in use, monthly charges are typically small.

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 (typically while the GitHub pull request is open).

You can optionally try to specify free or low-cost add-on plans in your app.json if those plans are sufficient to run and test your app.

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