Migrating to a GitHub App Integration

This guide will help you migrate your Portal instance to a GitHub App integration.

Why migrate to a GitHub App Integration?

The GitHub App integration provides a more secure and flexible way to integrate with GitHub. It allows you to have more control over the permissions and access to your GitHub repositories. Github Apps can be installed at the organization level instead of the user level as is the case with a Personal Access Token. By using a Github App, all commits made on behalf of Portal will automatically be signed.

Prerequisites

Before you start the migration, make sure:

• You have setup Portal and have access to the Config Manager.
• You have administrative access to your GitHub organization.

Steps to migrate

1. Create a GitHub App

1. Follow the GitHub documentation to create a new GitHub App.

   Make sure you create your GitHub App under a GitHub organization to allow easier management and shared ownership. If you don't have a GitHub organization to create it under, you can still create the app under a user and install it on an org, but this requires additional permissions to work (Organization permissions → Administration → Read/Write)

2. Set the following permissions for the app

   Repository permissions:

   Permission	Access Level
   Administration	Read / Write
   Actions	Read / Write
   Code scanning alerts	Read
   Commit statuses	Read
   Contents	Read / Write
   Dependabot alerts	Read
   Issues	Read / Write
   Metadata	Read
   Pull requests	Read / Write
   Repository security advisories	Read
   Secret scanning alerts	Read

   Organization permissions:

   Permission	Access Level
   Members	Read

3. Generate a private key for the app and save it securely.

4. Install the app on your GitHub organization.

2. Update Portal configuration

1. Go to the Config Manager and select App and then find integrations

Can be found via /config-manager/app#root~1.integrations~1.github__title

2. Expand the integrations, github and Github-1 sections.
3. Remove the token field, by clicking the x button within the field.
4. Expand the apps section, select the + Add Item button. A new section called apps-1 should appear.
5. Expand the new apps-1 section then add the following fields:

• appId - The App ID of the GitHub App you created.
• privateKey - The private key you generated for the GitHub App.
• webhookSecret - The webhook secret of the GitHub App.
• clientId - The Client ID of the GitHub App.
• clientSecret - The Client Secret of the GitHub App.

6. Scroll to the bottom of the page and click Save changes.