Skip to main content

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.

  2. Set the following permissions for the app

    Repository permissions:​

    Commit statuses: Read-only

    Administration: Read and write

    Actions: Read and write

    Contents: Read and write

    Metadata: Read-only

    Pull requests: Read and write

    Issues: Read and write

    Org permissions:​

    Members: Read-only

  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.integrations.github__title

  1. Expand the integrations, github and Github-1 sections.
  2. Remove the token field, by clicking the x button within the field.
  3. Expand the apps section, select the + Add Item button. A new section called apps-1 should appear.
  4. 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.
  1. Scroll to the bottom of the page and click Save changes.