Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 37 ยท CI, Pipelines and Review Apps

Review Apps and app.json

Create a disposable Heroku app for every pull request with review apps: app.json structure, env defaults, add-ons, the postdeploy script, seed data and automatic cleanup.

A review app is a complete, temporary copy of your application created automatically for a pull request. Reviewers click a link and try the change in a real environment instead of reading a diff. When the pull request is merged or closed, the review app is deleted. They are the most loved feature of pipelines, and they depend on one file: app.json.

The platform cannot run on this site, so the file examples are read-only and the checks are runnable Python stand-ins.

Turning review apps on

In the pipeline's dashboard, connect the GitHub repository and choose Enable Review Apps. Options include creating one automatically for each pull request or only on demand, destroying stale ones after a number of days without a new commit (the default is a few days), and sharing config vars from a parent app. Review apps use their own, small dynos and their own add-ons, so they cost money while they exist. Keep them small and short-lived.

app.json

app.json lives in the root of the repository. It describes the app for Heroku: name, description, environment variables, add-ons, buildpacks, formation and scripts. A practical example:

JSON
{
  "name": "shop",
  "description": "Demo shop",
  "env": {
    "SECRET_KEY": { "generator": "secret" },
    "APP_MODE": { "value": "review" },
    "STRIPE_KEY": { "required": true }
  },
  "addons": ["heroku-postgresql:essential-0", "heroku-redis:mini"],
  "buildpacks": [{ "url": "heroku/python" }],
  "formation": { "web": { "quantity": 1, "size": "basic" } },
  "scripts": { "postdeploy": "python manage.py migrate && python seed.py" },
  "environments": {
    "review": { "addons": ["heroku-postgresql:essential-0"] },
    "test": { "scripts": { "test": "pytest -q" } }
  }
}

What each part does:

  • env: variables the new app gets. value sets a fixed one, generator: "secret" makes a random string for each app (good for session keys), required: true asks the person who creates the app to provide a value. Prefer sandbox keys of external services here, never production secrets.
  • addons: add-ons created with the app. Choose the smallest plan.
  • buildpacks: the build steps, in order.
  • formation: how many dynos of which type.
  • scripts.postdeploy: runs once, right after the review app is first created. Use it for migrations and sample data.
  • environments.review overrides or adds settings only for review apps; environments.test is for Heroku CI.

postdeploy runs only when the app is created, not on later commits to the same pull request. Schema changes on later commits belong to the release phase (release: in the Procfile), which runs on every release.

Seed data

An empty review app is hard to review. A seed.py (or rails db:seed) script that creates a few users, products and an admin account lets the reviewer log in at once. Make the data obviously fake, never copy production data into a review app, and print the test login to the logs or the pull request description.

Cost control

Because every open pull request has its own app, costs scale with the team. Reduce them like this:

  1. Use the smallest dyno and add-on plans.
  2. Set the stale-destroy period to a few days.
  3. Create review apps on demand for big changes if the team opens many tiny pull requests.
  4. Do not give review apps a Standard database; use Essential or an in-memory option.
Python Stand-in: estimate the cost of review apps

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The same open pull requests cost over three times as much when they stay around ten days instead of three. Closing and merging promptly is the cheapest optimization.

Checking app.json before you push

A broken app.json fails when the review app is created, which wastes a cycle. A small script in CI can catch the common mistakes. This one is a stand-in checker with a few rules.

Python Stand-in: lint an app.json

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

It reports the live-looking key and the oversized database, and passes the postdeploy check.

Review app workflow

flowchart LR
    A["Open PR"] --> B["Heroku creates<br/>review app"]
    B --> C["postdeploy seeds data"]
    C --> D["Link in the PR"]
    D --> E["Reviewer tries it"]
    E -->|"merge or close"| F["App deleted"]

Every pull request gets its own temporary, seeded environment.

Limits to remember

  • Third-party services that need a fixed callback URL (OAuth, payment webhooks) do not like random review-app hostnames. Use a proxy, a wildcard setup the provider supports, or test these flows on staging.
  • Review apps are public by default; anyone who knows the URL can open them. Do not put anything private in them, and consider basic auth.
  • File uploads vanish at the next restart, as everywhere on Heroku.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When does the postdeploy script run?

    postdeploy runs only at creation; use the release phase for per-release tasks.
  2. 2. What does generator: secret do in app.json env?

    It generates a random string per app, which suits session keys.
  3. 3. Why do review apps need their own add-ons?

    Isolation protects production and lets reviewers experiment safely.
  4. 4. How do you reduce review app cost?

    Cost scales with open apps, plan size and lifetime.

Summary

  • Review apps are disposable apps per pull request, described by app.json.
  • env, addons, formation and scripts.postdeploy shape the copy; environments.review overrides for review apps.
  • Seed fake data; never copy production data or use live keys.
  • Control cost with small plans and short lifetimes.

Next: Logging, Drains and Log Parsing