Skip to main content

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 Project

When you're creating a new project, you will be guided through several steps to get the project set up correctly. The first step is connecting your Github repositories, which looks like the following:

image

Clicking on "Connect to Github" will redirect you to a Github authorization and installation screen. From this screen, you can select which repositories Porter can access, and you can add or request installation in organization repositories:

image

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:

image

When Joining an Existing Project

After you've logged in to the Porter dashboard and joined an existing project, you can click on "Account Settings" through the dropdown on the top right, and then click "Connect your Github account":

image

The rest of the steps are identical to the when creating a new project section above.

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:

image

Verifying Installation

After you have installed the Porter Github App, you can verify that the Github app in the correct repositories by navigating to the "Launch" tab, selecting "Git repository" as the application source, and viewing the linked repositories (note: you must have provisioned a cluster in order to view this screen):

image

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.

image

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_.

Workflows (Read & write): required for Porter to write Github actions YAML files to the repository.

User Permissions

Email addresses (read-only): required for Porter to read your Github email address for authentication.