Adding/Updating the Porter Github App
In order to be able to deploy applications through GitHub repositories, you must first authorize the Porter GitHub App to access your repositories.
Adding the Porter Github App
When Creating a New Application
When you’re creating a new application, you will be prompted to install the Porter GitHub App.
After clicking “Install and Authorize,” you will be redirected back to the Porter dashboard. You can view which accounts the Porter Github App is able to access by clicking on “Account Settings” through the dropdown on the top right:
Requesting Installation
If you are trying to install the Github app into an organization repository, but you do not have full permissions for a repository, the Github installation will result in a requested installation for the Porter Github App. Your organization admin will be requested to approve this Github App Installation. If you request Github installation for this organization, you can direct users to this document, which should answer any questions that your organization admin may have.
Approving the Installation as an Organization Admin
As the organization admin, you should receive an email when a new Github App installation is requested. You can also navigate to your organization settings page and click on the Installed Github Apps tab, where you will see a request as follows:
Updating the Porter Github App
If the Porter Github App is not installed in the correct repositories, you should navigate to “Account Settings” through the dropdown on the top right, and then click Install Porter in more repositories.
Porter Github App Permissions
Note that when you grant access to the Porter Github App, you are granting access through your account, which means that other users invited to your project will not be able to view or use any of the personal repositories that you have linked. However, if the user has access to a Github organization, they will be able to use the same Github App installation in the organization, and thus the same organization repositories.
The Porter Github App requires several Github permissions in order to operate properly:
Repository permissions
Actions (Read & write): required for Porter to write Github actions YAML files to the repository.
Administration (Read & write): required for Porter to create a new Github environment called Preview for deployments. The administration API isn’t used otherwise.
Contents (Read & write): required for Porter to write Github actions YAML files to the repository.
Deployments (Read & write): required for Porter to request Github deployments to the Preview environment.
Environments (Read & write): required for Porter to create a new Github environment called Preview for deployments.
Metadata (Read-only): mandatory, required for Github apps that integrate with repositories.
Pull Requests (Read & write): required for Porter to add comments to Github PRs.
Secrets (Read & write): required for Porter to write a PORTER_TOKEN secret to the repository automatically. We do not read any secrets from the repository beyond those prefixed with PORTER_.
Webhooks (Read & write): required for Porter to create a Github repository webhook to trigger new preview environment runs.
Workflows (Read & write): required for Porter to write Github actions YAML files to the repository.
Organization permissions
Members (read-only): required for Porter to create a new Github environment called Preview for deployments.
Account Permissions
Email addresses (read-only): required for Porter to read your Github email address for authentication.