Preview environments are currently in
beta and are not enabled on Porter projects by default. Please reach out on Discord or over email if you'd like to participate in beta-testing preview environments.
Preview environments are isolated instances of your application used for testing purposes. You can configure Porter to create a preview environment for every new pull request made to your Github repository. There are three steps required to get preview environments working with your application:
- Make sure preview environments are enabled for your cluster
- Preview environments enabled for your desired Github repository
porter.yamlfile at the root of your repository
Enable Preview Environments for your Cluster
To enable preview environments for your cluster, navigate to the cluster dashboard. If preview environments are enabled for your project, you will see the first tab of the cluster listed as Preview Environments. Click Enable Preview Environments to enable them for your cluster.
Enable Preview Environments for your Repository
Next, you should enable preview environments for your specific repository. To do this, click on the Add Repository button and select the repository that you wish to enable preview environments in. If you're not seeing the correct list of repositories, follow the instructions here to add your repository. Then, click Add Repository again, and preview environments will be enabled for your repository.
To remove preview environments from a repository, click on the Configure button, which will pull up a list of the repositories where preview environments are currently enabled. Click on the delete icon next to the repository to remove the integration.
The last step is to create a
porter.yaml file for your application. This file specifies the list of applications and addons that you'd like to deploy, and the build configuration settings for your application. Here's an example
# The YAML reference version: v1 is the only option for now
# A list of resources to create
- # The name of this resource
# The source for this repository. Defaults to the web, worker, and job applications by default.
# The configuration for the application or addon.
# The build configuration for the application.
# The runtime configuration for the application.
Now that the repository has been added and the
porter.yaml file has been created, new PRs created will trigger a new preview environment, and updates to that PR will re-build and re-deploy the environment. Each time the preview environment is deployed, a Github comment will be added to the PR indicating the URL that the PR is deployed on:
Github App Permissions
If you previously installed the Porter Github App in your Github account, you will receive an email requesting updated permissions for the Github app. If you do not wish to test preview environments at this time, you can ignore this email. The existing Porter Github App will still work.
This section details the updated permissions that the Porter Github App is requesting.
To see the full list of requested permissions, go here.
Administration (Read & write): required for Porter to create a new Github environment called
Preview for deployments. The administration API isn't used otherwise.
Deployments (Read & write): required for Porter to request Github deployments to the
Environments (Read & write): required for Porter to create a new Github environment called
Preview for deployments.
Pull Requests (Read & write): required for Porter to add comments to Github PRs.