Skip to main content
Contact Support
Visit help.pluralsight.com/help for the most up to date information.
© 2004-2025 Pluralsight, LLC. All Rights Reserved.

GitHub app integration and migration

Tags:

Last updated

Now you can set up your integration between GitHub and Flow using a GitHub app. This authentication method has the benefit of:

  • More security: Take advantage of short-lived tokens, fine-grained permissions, and more granular repo access controls.
  • Higher rate limits: Rate limits are scalable and set per GitHub organization, which means Flow can ingest your data faster and with fewer disruptions.
  • Easier token management: Authentication is not tied to a user account. Just install the app on your GitHub organizations.

Note: GitHub organizations are also called Groups in Flow.

GitHub app authentication for Flow is currently in Beta. Please reach out to your Pluralsight contact to participate in the Beta experience. If you have a large number of GitHub organizations, let your contact know so we can talk through the best ways to ingest your data using the GitHub app.

Permissions

You must have a user with permission to install the GitHub app (external site, opens in new tab) on all organizations you want Flow to ingest data from.

If you're integrating with GitHub Enterprise Server, you must have a user with permission to register a new GitHub app (external site, opens in new tab).

When finishing the integration in Flow, you must have a user with permission to view GitHub app installations on organizations you want to ingest data from who is also a member of those organizations. We recommend using the same user credentials of the user who installed the GitHub app on your organizations. This user will authenticate via OAuth.

Note: The credentials of the user in Flow are only used at the moment of finalizing the integration and aren't used again later. If the user who created the integration leaves your organization, the integration with Flow won't be impacted as long as the app is still installed on your organizations. Trying to create multiple GitHub app integrations using the same OAuth credentials to retrieve organizations may result in errors. If you experience errors, wait 24 hours to try again.

back to top

Prerequisite steps to install the GitHub app

GitHub Cloud

Install the Flow GitHub app from the marketplace (external site, opens in new tab) on each organization you want Flow to ingest data from.

Note: If you don't see the app on the marketplace (external site, opens in new tab), use this link to access the Pluralsight Flow GitHub app.

GitHub Enterprise Server (Self-hosted)

Self-hosted GitHub doesn't have access to the public GitHub marketplace. You must register a new GitHub app (external site, opens in new tab) within our Enterprise Server instance, which Flow will use to ingest data.

Use the following information to register the app.

Note: Any setting not mentioned here can be left as the default setting.

  • App Name: Flow
  • Description: Add anything to help you identify the app later.
  • Homepage URL: https://www.pluralsight.com/product/flow
  • Callback URL: https://flow.pluralsight.com/accounts/complete/github-enterprise-app
  • Permissions: Read-only
    • Repository Permissions
      • Administration
      • Contents
      • Deployments
      • Discussions
      • Issues
      • Metadata
      • Pull Requests
    • Organization Permissions
      • Members
    • Account Permissions
      • Email addresses
  • Make sure these are unchecked:
    • Webhook Active
    • Request user authorization (OAuth) during installation
    • Enable device flow

Once the new GitHub app for Flow is registered:

  1. Copy the Client ID, Client secret, App ID, and Private key. You'll need this information to finish your integration in Flow.
  2. Install the GitHub app (external site, opens in new tab) on each GitHub organization you want Flow to ingest data from.

back to top

Create a new GitHub app-based integration in Flow

Note: After integrations are created, GitHub app-based integrations in Flow will behave the same as other integrations. However, you can't import teams from GitHub using integrations created with the GitHub app authentication method. Unlike OAuth or Personal access token-based authentication, both of which are tied to a specific user's permissions, GitHub app authentication does not rely on the same permissions structure. GitHub apps do not have any team management scopes, which are a requirement for importing teams from GitHub.

GitHub Cloud

  1. In Flow, navigate to Settings.
  2. On the Integrations page, click Add integration.
  3. Click the GitHub Cloud tile.
  4. Select GitHub app - Pluralsight Flow as your authentication method.
  5. Click Retrieve organizations via OAuth.
  6. In the pop-up modal, log in to the service account with the correct permissions. If asked, click Authorize Pluralsight Flow.
  7. Click Next.
  8. Select organizations
    • This list only includes organizations with the Flow GitHub app installed that the service account has permission to view.
    • Any orgs that have already been connected to Flow will be grayed out. Organizations can only be associated with one integration in Flow.

      Tip: If an organization is missing from the list, it's likely that it either doesn't have the app installed on it yet, or the service account doesn't have permission to see the organization.

  9. Click Next.
  10. Enable services for the integration.
  11. Confirm your organization selections. Remember that each selected organization will be associated with its own integration in Flow.
  12. Click Done.

Once you finish creating your integration, Flow creates a separate integration for each organization you selected, with the name of each integration the same as the name of the organization. Each integration and its repos are managed separately in Flow.

GitHub Enterprise Server (Self-hosted)

  1. In Flow, navigate to Settings.
  2. On the Integrations page, click Add integration.
  3. Click the GitHub Cloud tile.
  4. Select GitHub app - Pluralsight Flow as your authentication method.
  5. Click the GitHub Enterprise Server (Self-hosted) tile.
  6. Retrieve your organizations
    • If you've already created an integration with the GitHub app authentication method and want to use the same app, click Select pre-existing app, then choose your app. Click Retrieve organizations via OAuth. In the pop-up modal, log in to the service account with the correct permissions. If asked, click Authorize for the app.
      —or—
    • If you've never created an integration in Flow with the GitHub app authentication method or want to use a different app, click Create new GitHub app in Flow.
      1. Insert the following information:
        • GitHub app ID: Found in your GitHub app.
        • GitHub App name: We recommend using the same name you did when registering the GitHub app. Whatever name you choose, make it identifiable for future use.
        • Base URL: The base URL of your GitHub Enterprise Server instance, excluding the trailing slash.
        • Client ID: Found in your GitHub app.
        • Client secret: Found in your GitHub app.
        • Private key: Found in your GitHub app.
      2. Click Retrieve organizations via OAuth. In the pop-up modal, sign in to the service account with the correct permissions. If asked, click Authorize for the app.
  7. Click Next.
  8. Select organizations
    • This list only includes organizations with the Flow GitHub app installed that the service account has permission to view.
    • Any organizations that have already connected to Flow will be grayed out. Organizations can only be associated with one integration in Flow.

      Tip: If an organization is missing from this list, it's likely that it either doesn't have the app installed on it yet, or the service account doesn't have permission to see the organization.

  9. Click Next.
  10. Enable services for the integration.
  11. Confirm your organization selections. Remember that each selected organization will be associated with its own integration in Flow.
  12. Click Done.

Once you finish creating your integration, Flow creates a separate integration for each organization you selected, with the name of the integration the same as the name of the organization. Each integration and its repos are managed separately in Flow.

back to top

Migrate existing Flow integration to use GitHub app authentication

Important: Because GitHub apps are installed and scoped at the GitHub organization level, switching an existing integration to or from GitHub app authentication is not possible in Flow.

If you have an existing GitHub integration and would like to switch to using GitHub app authentication instead, create a new integration in Flow using the GitHub app - Pluralsight Flow authentication method as documented above. Once the new integration is set up, duplicate any settings you have for your previous integration into your new integrations, like git tag settings, repo exclusions, and import settings. This will help ensure your data is re-ingested correctly.

Once these settings are completed, delete your previous integrations. This will trigger Flow to remove the data associated with the previous integration, and re-ingest it under the new integration(s). Data ingestion can take some time, depending on the number of repos and integrations you have.

Note: Because Flow automatically prunes deleted branches from newly ingested data but doesn't prune deleted branches from already-ingested data, your historical metrics may change slightly when your data re-ingests. This is expected and nothing to be concerned about. Learn more about how deleted branches factor into Flow data.

back to top

Edit a GitHub app integration in Flow

Once they have been created, manage your integrations in Flow as usual. However, once an integration is created through the GitHub app authentication method, it can't be edited to use a different authentication method. If you need to switch authentication methods, create a new integration with the new method, then delete all GitHub app-based integrations.

If you use GitHub Enterprise Server, you can edit the Client ID, GitHub app name, Base URL, and Private key if they change in your system. To do this, on the Integrations page, click Edit GitHub apps. Every time you update any of these fields, you must re-enter the Private key to save the changes. Changing these fields for a GitHub app in Flow will automatically update all integrations created using that GItHub app.

Related articles