Skip to main content
Warning This document has not been updated for a while now. It may be out of date.
Last updated: 21 Jun 2023

Set up Heroku review apps for pull requests

Review apps allow us to automatically deploy application changes into a brand new Heroku app so that each Pull Request reviewer has a chance to see how it looks with live data.

These are examples of GOV.UK apps that have review apps enabled:

Follow the steps below in order to enable review apps for your GOV.UK application.

Use the shared Heroku account

GOV.UK has a shared Heroku account. This can be the owner of the review apps, as well as the associated pipelines for deploying the review apps.

Create a new Heroku app via the UI

Login to Heroku and create a new application in the European availability zone. Give the app a meaningful name to closely match the application name on GitHub.

Enable your app to work on Heroku

There are 3 things needed to be configured before you can deploy your app to Heroku:

  • Add a Procfile that tells Heroku how to run your application;
  • Add a file called app.json with the expected app configuration.
  • Ensure the Gemfile references the correct Ruby version

An example Procfile for a standard Rails application will look something like this:

web: bin/rails server -p $PORT -e $RAILS_ENV

This is telling Heroku to run the standard Rails server on the given port and environment, both set in the Heroku environment.

A standard app.json file for a Rails project will look somewhat like this:

  "name": "govuk-app",
  "repository": "",
  "env": {
      "value": ""
      "value": ""
      "value": ""
      "value": ""
      "value": ""
      "value": "yes"
      "generator": "secret"
      "required": true
  "image": "heroku/ruby",
  "buildpacks": [
      "url": ""
  "addons": []

There is more information about it on the Heroku Dev Center.

Each GOV.UK application will have a set of dependencies, so the level of configuration will vary. However, for most apps, you will need a number of environment variables configured before you can successfully deploy the app to Heroku.

Check out the app.json files on both collections and government-frontend for examples of necessary environment variables.

You can create the application via the app.json file.

You will need a successful deploy with a correct configuration before you can deploy review apps.

Your Gemfile should contain logic to ensure it’s using the same Ruby version as our infrastructure:


See smart-answers for an example of this.

If all goes well, you will be able to see your app on:

Choose the most appropriate plan for your app

To change the plan you have to go into the resources tab in the app and click on “change dyno type”. Most apps should be on the Eco plan and share dyno hours with other apps. If you expect your app to be accessed frequently you should pick the Basic plan, this is because the dyno hours on the Eco plan might run out and all apps on that plan will stop working.

Create a new pipeline on Heroku

Once you have a successful deployment of your app into Heroku and the app.json file commited to the repository and in your main branch, you will now be able to start using review apps.

On Heroku, create a new pipeline and enable automatic review apps when prompted. At this point, every new Pull Request being opened on the GOV.UK application will have a new review app being created from the app.json template and the link will automatically be posted into the GitHub Pull Request.

That’s it! Now try to create a new test Pull Request and verify that the application is being deployed to a new review app.