Set up Heroku review apps for pull requests

Last updated: 15 Apr 2026

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": "https://github.com/alphagov/govuk-app",
  "env": {
    "GOVUK_APP_DOMAIN": {
      "value": "www.gov.uk"
    },
    "GOVUK_WEBSITE_ROOT": {
      "value": "https://www.gov.uk"
    },
    "PLEK_SERVICE_CONTENT_STORE_URI": {
      "value": "https://www.gov.uk/api"
    },
    "PLEK_SERVICE_SEARCH_URI": {
      "value": "https://www.gov.uk/api"
    },
    "PLEK_SERVICE_STATIC_URI": {
      "value": "assets.digital.cabinet-office.gov.uk"
    },
    "RAILS_SERVE_STATIC_ASSETS": {
      "value": "yes"
    },
    "SECRET_KEY_BASE": {
      "generator": "secret"
    },
    "HEROKU_APP_NAME": {
      "required": true
    }
  },
  "image": "heroku/ruby",
  "buildpacks": [
    {
      "url": "https://github.com/heroku/heroku-buildpack-ruby"
    }
  ],
  "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 frontend for examples of necessary environment variables.

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

Connecting the Heroku app to the Github repo

You will need a successful deploy with a correct configuration before you can deploy review apps. You can set up deployments in Heroku by using the deploy tab on the app, then choosing Deployment method: Github and searching for the repo. (Note that the github account that is logged into Heroku to give access to the apps is govuk-ci, but you should choose alphagov as the account to search)

This will cause Heroku to create a webhook in the github repo (you can confirm this in the repo’s settings->Webhooks)

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

ruby File.read('.ruby-version').chomp

See smart-answers for an example of this.

If all goes well, you will be able to see your app on: https://govuk-app.herokuapp.com

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.

Rotating the webhook secrets

If you need to rotate the secret used by the webhook, note that this cannot be done in Github - there’s an option in Github that allows you to manually change the secret, but there’s no option to set it in Heroku. You will need to disconnect the heroku app from the Github repo, then reconnect it. You may need to recreate the pipeline after this.