Configure Scalingo Review Apps for Automatic Ephemeral Environments per Pull Request

Desired Outcome

After completing this guide, every pull request opened against your linked GitHub repository will automatically trigger Scalingo to create a temporary Review App. The Review App will use the same codebase and addon configuration as your parent app, be accessible via a unique subdomain (e.g., pr-123.myapp.scalingo.io), and be destroyed when the PR is closed or merged.

Prerequisites

• A Scalingo account with a paid plan (Review Apps are not available on the free tier).
• An existing Scalingo application that you want to replicate for Review Apps.
• Access to the GitHub repository containing the application source code.
• The Scalingo CLI installed locally (scalingo --version should return a valid version).
• Sufficient dyno‑hour and addon quota to cover the additional temporary apps.

Procedure

1. Link the Scalingo app to GitHub

1. Log in to the Scalingo Dashboard and navigate to your application.
2. Select the "Integrations" tab, then choose "GitHub" and click "Link repository".
3. Authorize Scalingo to access your GitHub account (if not already authorized) and select the target repository.
4. Confirm the link. The dashboard will show a "Linked" status and display the webhook URL that Scalingo has registered.

2. Add a scalingo.yml manifest to the repository

Create a file named scalingo.yml at the root of the repository. This file defines the buildpack, environment variables, and any addons that should be provisioned for each Review App.

# scalingo.yml example
buildpacks:
  - https://github.com/scalingo/nodejs-buildpack

env:
  # Inherit from parent app unless overridden
  NODE_ENV: development
  # Example of a non‑secret override
  API_URL: https://api.example.com

addons:
  - scaleredis:dev  # lightweight dev‑only redis
  # Uncomment the line below only if you need a persistent DB for testing
  # - scalepostgresql:dev

Commit and push this file to the default branch (e.g., main).

3. Manage secret environment variables

Never store secrets (API keys, database passwords) in scalingo.yml because the file is version‑controlled. Instead, set them via the Scalingo CLI or dashboard for the parent app; they will be automatically inherited by Review Apps.

# Example: set a secret for the parent app (run locally)
scalingo --app myapp env-set SECRET_KEY=your‑actual‑secret

If a Review App needs a different value for a secret, you can override it after the Review App is created:
# Replace  with the actual name shown in the dashboard
scalingo --app pr-123-myapp env-set SECRET_KEY=review‑specific‑value


4. Trigger a Review App
Open a new pull request against the linked repository. Scalingo receives the GitHub webhook, provisions a Review App, and assigns it a subdomain based on the PR number.

Expected Checks
Dashboard verification

  
In the Scalingo Dashboard, open the "Review Apps" section of your parent app.
  
Confirm an entry appears with a name like pr-123-myapp and a status of "Running".
  
Click the entry to view the assigned URL (e.g., https://pr-123-myapp.scalingo.io).


Log verification
# Run locally; replace  with the actual name
scalingo --app pr-123-myapp logs

Look for successful buildpack detection, slug compilation, and the expected process types (e.g., web.1). Absence of error traces indicates a healthy deployment.

URL accessibility
Using curl or a browser, request the Review App URL and verify you receive a 200 response from your application (or the expected landing page).

Recovery Options (Rollback)
Linking the app to GitHub and adding scalingo.yml changes state. To revert:

  
Unlink the GitHub repository:
  

    
In the Scalingo Dashboard → "Integrations" → "GitHub", click "Unlink".
  
  
Remove scalingo.yml from the repository and push the change.
  
Optionally, delete any lingering Review Apps manually:
  

    
In the "Review Apps" list, select each app and choose "Delete" (or close/merge the associated PR to trigger automatic teardown).
  

After unlinking, new PRs will no longer trigger Review Apps. Existing Review Apps that were already created will remain until manually deleted or until their associated PR is closed/merged.

Limitations and Practical Tips

  
Review Apps consume the same dyno‑hour and addon quotas as regular apps. Monitor usage in the Dashboard → "Resources" to avoid unexpected charges.
  
Heavy addons (e.g., large PostgreSQL instances) can exhaust quotas quickly. Consider using dev‑only plans or disabling non‑essential services in scalingo.yml for Review Apps.
  
Environment variables defined only in scalingo.yml are visible to anyone with repository read access. Keep secrets out of the file and manage them via the Scalingo CLI or dashboard.
  
Review Apps are subject to Scalingo’s fair‑usage limits; if you hit a limit, provisioning may be delayed or fail.