Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Working with Bundler
      • Rails Support
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with the Play Framework
      • Working with Spring Boot
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Data For Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Single Sign-on (SSO)
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Extending Heroku
  • Review Apps (New)

Review Apps (New)

English — 日本語に切り替える

Last updated February 06, 2023

Table of Contents

  • Setup
  • Selecting the URL pattern
  • Setting up permissions
  • Creating review apps
  • Viewing review apps
  • Configuration
  • Review apps and CI
  • Review apps and Heroku Private Spaces
  • Review apps and Docker
  • Review apps management and costs
  • Review apps API
  • Feature Changes
  • Permission Changes
  • FAQ

This article is about the new version of Heroku Review Apps released to General Availability (GA) on November 7th 2019. If you are using the older version, we highly encourage you to upgrade. Users who enable Review Apps for the first time on/after November 7th will have the new version of Review Apps enabled by default. Starting November 7th, the older version of Heroku Review Apps will no longer be supported with the CLI. CLI commands can be used to enable, disable or configure this new version of Heroku Review Apps only. If you plan to upgrade from the older version of Heroku Review Apps to the new version and benefit from the new features, please refer to this Knowledge Base article for simple migration instructions.

 

You can not go back to the old version of Heroku Review Apps once you upgrade to the new version.

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. Connect pipeline to 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.

Set Pipeline Config Variables

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:

New Users RA

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: Enable New Review Apps

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

If you are upgrading and have failed pull requests or don’t have the “Automatically create apps” option selected to generate review apps for your PRs automatically, you won’t see a review app in the new version after the upgrade. Please check for failed PRs and update the Review Apps creation options to get the best results.

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.

Enable New Review Apps

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.

For users of the older version of Review Apps, the new pipeline level ephemeral app permissions can’t be used to manage Review Apps permissions. If user has CI enabled though, she can use these permissions to manage user access to CI apps.

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.

Enable New Review Apps

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.

Only review apps which are automatically created are automatically destroyed when the PR is closed.

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):

Deploy Notification

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

Review apps on the Heroku Pipelines 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.

Review app log

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.

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.

 

The new version of review apps does not depend on parent apps. All configuration for this new version should exist in theapp.json or the pipeline Settings tab.

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:mini"]
    }
}

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.

The size of the dyno on which the command will be run can be configured by specifying an object with command and size keys.

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.

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 to a Review apps is not currently supported. Copying production data to test apps means risk of data leaks or other programming mistakes operating on recent customer data. Instead, we recommend seeding databases comprehensively with non-production data using seed scripts run with the postdeploy command.

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.

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.

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

The size of the dyno on which the command will be run can be configured by specifying an object with command and size keys.

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.

HEROKU_APP_NAME, HEROKU_BRANCH and HEROKU_PR_NUMBER 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.

Only check “Wait for CI to pass” in Review Apps settings if either Heroku CI or another CI service runs on every commit to your app. Otherwise, Review Apps may wait indefinitely for tests to pass when no CI is configured.

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:

Manage Heroku review apps from the Pipeline’s main page.

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

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.

Keep reading

  • Extending Heroku

Feedback

Log in to submit feedback.

Webhook Events Webhook Events

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

Your email address:

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
  • YouTube
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies
  • Cookie Preferences