# Review Apps

> Spin up a real environment for every pull request, automatically.

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:

```json
{
  "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](https://docs.watasu.io/reference/app-json.md).

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

```json
{
  "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](https://docs.watasu.io/reference/pod-sizes.md) 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)

[View this page on the web](https://docs.watasu.io/workflows/review-apps/)