Review Apps

Review apps create a temporary, fully working environment for each pull request. Reviewers click a real link, exercise real code, and see real config — instead of trying to imagine what your branch does from a diff.

What happens

When a pull request opens against a connected repository:

1. Watasu creates a preview app
2. Provisions the add-ons declared in app.json
3. Deploys the PR’s source
4. (Optionally) runs scripts.postdeploy to seed data, run migrations, etc.
5. Posts the preview URL back to the pull request as a comment, so reviewers can click straight through

When the pull request closes or merges (or is converted to a draft):

1. (Optionally) runs scripts.pr-predestroy for any cleanup
2. Tears down the preview app and its add-ons

Requirement: app.json

app.json is required for review apps. It’s how Watasu knows what to provision and configure for each PR.

A minimal app.json for review apps:

{
  "env": {
    "RAILS_ENV": { "value": "production" }
  },
  "addons": [
    "postgresql:hobby-0",
    "valkey:hobby-0"
  ],
  "formation": {
    "web": { "quantity": 1, "size": "standard-1x" }
  },
  "scripts": {
    "postdeploy":   "bundle exec rails db:prepare && bundle exec rails db:seed",
    "pr-predestroy": "bundle exec rails app:cleanup"
  }
}

For the full schema, see Reference → app.json Schema.

Process sizes and inheritance

A review app starts from its parent app’s current process formation and caps every process at one replica. If the parent uses dynamic-1x, the review app uses dynamic-1x too; if it uses standard-2x, the review app inherits standard-2x.

The effective app.json formation then applies on top. Use environments.review when review apps should have a different size without changing the parent app:

{
  "environments": {
    "review": {
      "formation": {
        "web": { "quantity": 1, "size": "dynamic-1x" },
        "worker": { "quantity": 1, "size": "dynamic-2x" }
      }
    }
  }
}

Dynamic pods are often a good fit for review apps: the process stays reachable for reviewers but bills measured CPU and memory while it is quiet. See Pod Sizes for rates and hard ceilings.

Good uses

• design and product reviews on real UI
• migration and seed-data validation against real databases
• integration tests against real attached add-ons
• stakeholder demos before merging

Operational advice

Review apps are real environments that cost real resources. A few rules of thumb:

• pick small plans for review-app add-ons (postgresql:hobby-0, valkey:hobby-0) — they don’t need production sizing
• let process sizes inherit when the parent already has the right cost profile; use environments.review.formation only for deliberate review-specific overrides
• don’t bake long-lived production secrets into app.json. Set those out-of-band on the parent app.
• use pr-predestroy for any cleanup that needs to happen before the environment goes away (notifying systems, archiving logs)