Automatic Staging Environments for Pull Requests

App Platform can automatically create a staging environment whenever you open a pull request in GitHub. Each environment is a separate deployment of your app built from the pull request's branch, with its own technical domain. Use it to test changes before merging them into the target branch.

While the pull request is open, every new commit you push to the branch updates the environment. For general information about staging environments, see Staging Environments.

Requirements and Limits

Copy link

• Your repository must be connected through your GitHub account. Repositories connected by URL are not supported.
• Each app can have up to 10 staging environments. Once you reach the limit, new pull requests won't get an environment, even if automatic deploy is enabled.
• The setting is per app. If several apps are deployed from one repository, only those with the setting enabled get staging environments. See Monorepos.

Enable Automatic Staging Environments

Copy link

1. Go to App Platform and select your app.
2. On the Stands tab, click Automation.
3. Turn on Automatic deploy on Pull Request.
4. (Optional) Turn on Pass application variables automatically to copy your app's variables into new staging environments. See Environment Variables below.
5. Click Save.

Open a pull request in the connected repository. App Platform creates a staging environment and starts the deployment.

Pass Variables to Staging Environments

Copy link

By default, a new staging environment doesn't inherit the variables of your main app. You can change this so they're copied automatically. The setting applies to all staging environments of the app, including those you create manually.

1. Go to App Platform and select your app.
2. On the Stands tab, click Automation.
3. Turn on Automatic deploy on Pull Request.
4. Turn on Pass application variables automatically.
5. Click Save.

Keep in mind:

• Variables are copied only once, when the environment is created. If you later change the variables of your main app, update the staging environment separately.
• If you copy connection parameters for a database or an external service, the staging environment will use the same resource as your production app. To avoid changing production data during testing, set separate values in the staging environment's settings instead.

Allow Comments in GitHub

Copy link

When a staging environment is created, the Hostman Apps bot posts a comment in the pull request with the deployment status and links to the environment. To do this, the GitHub integration needs read and write access to pull requests.

New integrations have this permission by default, including those you disconnect and reconnect in the App Platform dashboard. Integrations connected earlier may need updated permissions. Without them, staging environments are still created, but no comments appear in GitHub.

If you don't see a warning in step 2 below, no action is needed.

1. Go to App Platform and select your app.
2. On the Stands tab, click Automation. If you see the No access to GitHub comments warning, continue with the next steps.
3. Click Configure access in the warning.
4. In GitHub, on the Installed GitHub Apps tab, find Hostman Apps and click Review request.
5. Check that the requested permission is Read and write access to Pull requests, then click Accept new permissions.

Hostman Apps requesting updated permissions in GitHub

Monorepos

Copy link

If a repository contains several apps, App Platform checks which files a pull request changes and creates an environment only for apps whose source directory is affected.

For example, say your repository has frontend and backend directories, and your app is deployed from frontend:

• A pull request that changes files in frontend creates a staging environment.
• A pull request that changes only backend doesn't create one.

If a pull request changes more than 300 files, GitHub can't compare the changes. In this case, App Platform creates a staging environment regardless of which directories were affected.

Staging Environment Lifecycle

Copy link

App Platform manages the environment based on what happens to the pull request in GitHub:

What you see after creation

The environment appears on the Stands tab with a PR label and a name based on the pull request number. For example, pull request #1 creates PR-1. The list shows the branch, commit, commit message, and deployment status.

After a successful deployment, the app is available at the environment's technical domain. You can find it in the environment's settings in the dashboard and in the bot's comment in the pull request. The bot updates this comment with the latest commit and deployment status on each redeploy.

Manage a Staging Environment

Copy link

To open an environment's settings, go to App Platform → your app → Stands and click the environment. From there you can rename it, manage its variables, and copy its technical domain. To view logs, open the Stand logs tab.

For more details, see Manage Staging Environments.

Deploy a Specific Commit

Copy link

By default, a pull request environment is built from the latest commit and redeploys on every push. You can't change its source branch, but you can pin it to a specific commit:

1. Go to App Platform and select your app.
2. On the Stands tab, click the environment.
3. Turn off Build from latest commit.
4. Select a commit.
5. Click Save.

The environment stops updating automatically, and the bot posts a note in the pull request saying the environment is pinned to the selected commit.

Keep an Environment After the Pull Request Is Closed

Copy link

You can turn off automatic deletion for pull request staging environments, so they stay available after the pull request is closed.

1. Go to App Platform and select your app.
2. On the Stands tab, click the environment.
3. Turn off Delete stand when Pull Request is closed.
4. Click Save.

Now closing or merging the pull request will not delete the environment. Delete it manually when you no longer need it.