Skip to main content

Review apps: a preview environment per pull request

Review Apps automatically create temporary preview environments for each pull request (PR) or merge request (MR), enabling teams to test and review changes before merging them into the main branch.

What are Review Apps?​

Review Apps are temporary deployments of your application that are automatically created when you open a pull request on GitHub or a merge request on GitLab. Each review app is an isolated environment that runs your application with the code changes from the PR/MR, allowing you to:

  • Test new features in a production-like environment
  • Share working previews with stakeholders
  • Perform QA and testing before merging
  • Catch bugs early in the development cycle

Key Features​

  • Automatic Creation: Review apps are automatically created when a PR/MR is opened
  • Automatic Updates: Each new commit to the PR/MR triggers a new deployment to the review app
  • Automatic Cleanup: Review apps are automatically deleted when the PR/MR is closed
  • TTL-based Expiration: Review apps automatically expire after a configured number of days
  • Resource Configuration: Customize CPU, memory, and other resources for review apps
  • Inherits Configuration: Review apps clone the parent app's configuration, including environment variables, workers, and cron jobs

Prerequisites​

Before enabling review apps, ensure your app has:

  1. A Git repository configured (GitHub or GitLab)
  2. A Git platform connection (GitHub or GitLab OAuth)
  3. Webhooks properly configured in your repository settings

Enabling Review Apps​

To enable review apps for your application:

  1. Navigate to your app's Settings page
  2. Click on the Review Apps tab
  3. Toggle the Enable Review Apps switch
  4. Configure the TTL (Time To Live) in days (default: 7 days)
  5. Optionally configure resource overrides (see below)
  6. Click Save Changes

Review Apps Settings

Configuration Options​

TTL (Time To Live)​

Review apps automatically expire after the configured number of days. This helps prevent orphaned review apps from consuming resources.

  • Minimum: 1 day
  • Maximum: 30 days
  • Default: 7 days

Resource Overrides​

You can override resource limits for review apps to use smaller (or larger) resources compared to your production app:

Build Resources​

  • Build CPU: Override the CPU allocated for building review apps
  • Build Memory: Override the memory (in MB) allocated for building review apps

Web Process Resources​

  • Min CPU: Minimum CPU for the web process
  • Min Memory: Minimum memory (in MB) for the web process

Worker Processes​

  • Inherit Workers: Toggle whether to inherit worker processes from the parent app
  • Custom Workers: Define custom worker processes specific to review apps

Cron Jobs​

  • Inherit Cron Jobs: Toggle whether to inherit cron jobs from the parent app
  • Custom Cron Jobs: Define custom cron jobs specific to review apps
tip

If you don't configure resource overrides, review apps will inherit all settings from the parent app. This is useful for ensuring consistency but may consume more resources than necessary for testing environments.

How Review Apps Work​

GitHub Workflow​

  1. PR Opened: When you open a pull request, Hostless receives a webhook and creates a new review app
  2. Naming: Review apps are named {parent-app-name}-pr-{number} (e.g., myapp-pr-123)
  3. Deployment: The review app is automatically deployed with the code from the PR branch
  4. Updates: Each new commit pushed to the PR triggers a new deployment
  5. Status Comments: Deployment status is posted as a comment on the PR with the review app URL
  6. PR Closed: When the PR is closed or merged, the review app is automatically deleted

GitLab Workflow​

  1. MR Opened: When you open a merge request, Hostless receives a webhook and creates a new review app
  2. Naming: Review apps are named {parent-app-name}-pr-{number} (e.g., myapp-pr-123)
  3. Deployment: The review app is automatically deployed with the code from the MR branch
  4. Updates: Each new commit pushed to the MR triggers a new deployment
  5. Status Comments: Deployment status is posted as a comment on the MR with the review app URL
  6. MR Closed: When the MR is closed or merged, the review app is automatically deleted

Viewing Review Apps​

To view all review apps for your application:

  1. Navigate to your app's page
  2. Click on the Review Apps tab
  3. You'll see a list of all active review apps with:
    • Review app name
    • Pull/Merge request number and link
    • Branch name
    • Expiration date
    • Current status
    • Action buttons (View App, Open URL, Deployments, Delete)

Review Apps List

Managing Review Apps​

Manual Deletion​

To manually delete a review app before it expires:

  1. Navigate to the Review Apps tab
  2. Find the review app you want to delete
  3. Click the Delete button
  4. Confirm the deletion
warning

Deleting a review app is permanent and cannot be undone. All data and deployments associated with the review app will be lost.

Accessing Review Apps​

Review apps are accessible via a Hostless subdomain:

https://{app-name}-pr-{number}.{hostless-domain}

For example:

https://myapp-pr-123.apps.hostless.cloud

You can find the URL in:

  • The PR/MR comment posted by Hostless
  • The Review Apps list in your app's dashboard
  • The review app's detail page

Best Practices​

1. Use Smaller Resources​

Configure resource overrides to use smaller CPU and memory allocations for review apps, as they typically don't need production-level resources.

2. Keep TTL Reasonable​

Set an appropriate TTL to automatically clean up review apps. 7 days is usually sufficient for most teams.

3. Don't Inherit All Workers​

If your production app has heavy background workers, consider disabling worker inheritance for review apps to save resources.

4. Test in Review Apps​

Encourage your team to test changes in review apps before merging to catch issues early.

5. Share Review App URLs​

Share review app URLs with stakeholders, designers, and QA teams for feedback before merging.

Limitations​

  • Custom Domains: Review apps do not support custom domains. They are only accessible via the Hostless subdomain.
  • Nested Review Apps: Review apps cannot have their own review apps.
  • Environment Variables: Review apps inherit environment variables from the parent app. Sensitive variables will be copied to review apps.
  • Database: Review apps do not have isolated databases unless explicitly configured.

Troubleshooting​

Review Apps Not Creating​

If review apps are not being created:

  1. Check Webhook Configuration: Ensure webhooks are properly configured in your repository settings
  2. Verify Git Connection: Make sure your Git OAuth connection is active
  3. Check Review Apps Setting: Confirm that review apps are enabled in your app settings
  4. Review Logs: Check the deployment logs for any errors

Deployment Failures​

If a review app deployment fails:

  1. Navigate to the review app's Deployments tab
  2. Click on the failed deployment
  3. Review the build and deployment logs
  4. Fix any issues in your code and push a new commit

Expired Review Apps​

If a review app expires and is deleted while you're still working on the PR/MR:

  1. Push a new commit to the PR/MR to trigger a new deployment
  2. If the review app was already deleted, close and reopen the PR/MR to create a new one
  3. Consider increasing the TTL in your review app settings if review apps are expiring too quickly

Cost Considerations​

Review apps consume resources and incur costs based on:

  • Number of concurrent review apps
  • Resources allocated (CPU, memory)
  • Duration (TTL)

To optimize costs:

  • Use resource overrides to allocate smaller resources
  • Keep TTL short (7 days or less)
  • Disable worker and cron job inheritance if not needed
  • Delete review apps manually when no longer needed