Review Apps (Old)
Last updated May 18, 2023
This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.
Table of Contents
A new version of Heroku Review Apps is available. If you are using review apps, we highly encourage you to upgrade to the new version and benefit from the new features and improvements. To learn more about the new Heroku Review Apps and the upgrade process, please read the new documentation.
Starting November 7th, this version of Heroku Review Apps will no longer be supported with the CLI. CLI commands can be used to enable, disable or configure the new version of Heroku Review Apps only. Additionally, you cannot revert to the old version of Review Apps once you upgrade to the new version.
Review apps run the code in any GitHub pull request in a 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.
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.
See the app.json section below for more information.
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
Your review apps should inherit their configuration from a development or staging version of your app only. Inheriting from production could inadvertently leak production data to a testing environment.
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.
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.
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
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
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.
Some add-ons do not support review and CI apps. You’ll see an error message like
<add-on service slug> has opted out of supporting Review and CI apps if you attempt to use an add-on that has opted out of Review and CI app support.
Any required config vars specified in the
env section of the
app.json file must either have a
value, use a
generator, or inherit from the parent app (see below). If the
env section specifies required config vars where a value can not be resolved, no app will be created for that pull request.
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:
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.
required and non-required config vars can be inherited.
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
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.
If your post-deploy script fails, we will recreate the app on the next push and execute the post-deploy script again.
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.
Copying full database contents from parent to Review apps (similar to
heroku fork) is not currently supported. Copying production data to test apps means risk of data leaks or other programming mistakes operating on recent customer data. For those reasons, we instead recommend seeding databases comprehensively with non-production data using seed scripts run with the
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.
pr-predestroy script to tear down any resources provisioned during
postdeploy and to do other clean-up.
The command is prefixed with “pr-” because it is ONLY run as part of the pull request (PR) app flow.
Output from this script is not sent to the log drain.
To help with scripting, two special config vars are available to review apps. If you specify
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
"postdeploy":"rake db:setup && bin/bootstrap"
HEROKU_PARENT_APP_NAME are likely to change. They’re only available via the review app creation flow and will not be updated if apps are renamed.
Disabling review apps
You can disable review apps at any time. Doing so prevents new review apps from being created.
Disabling review apps also deletes existing associated review apps.
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
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.
Use the ‘formation’ directive in the parent’s app.json to configure non-default dynos for your review apps.
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.
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.