GitHub Enterprise Setup

Tags: Flow

This is a step-by-step guide for connecting your GitHub Enterprise account to Flow. If your repositories are behind a firewall, please allowlist our IPson port 443 over HTTPS. You also need a public DNS record pointing to the IP address that is being exposed for Flow analysis. This DNS entry should match the TLS/SSL certificate the server is utilizing.

Who can use this?

 Core
Plus
 
  

 

Important: We strongly recommend you use a service account to create this Integration. See How to create a service account for instructions and information about why service accounts are important.

Permission requirements

In order to utilize all integration services, including pull requests, tickets, and webhooks, the service account needs to be an owner on the GitHub organization. 

If the service account is only a member of the organization, webhooks will not be available in Flow. All other services such as repos, PRs, and tickets will be available. 

Webhook permissions

In order to enable Webhooks, the service account needs to be a GitHub organization owner and at least one repo needs to be imported from the organization. Learn more about webhooks 

OAuth Permissions

Flow only requires read access to your repositories. Flow needs this permission to process the metadata used to generate our reports. 

GitHub does not offer the ability to narrow permissions down to just read-only access to private profile information and repositories. When connecting to GitHub, their standard Oauth permissions include write and full admin permissions. These permissions are never used by our system. These access levels are required in order to utilize GitHub APIs. To learn more about OAuth permissions, click here.

Connecting to GitHub Enterprise

There are three ways you can connect to your GitHub Enterprise account:

  1. OAuth requires you to create an OAuth application in your GitHub Enterprise account. 
  2. Username and Password connects with your GitHub Enterprise login credentials. 
  3. Access Token requires you to create an access token in your GitHub Enterprise account. 

To connect your GitHub Enterprise, first create a new integration. 

  1. In the top navigation bar, click Settings. 
  2. In the left navigation under Integrations, click Integrations.
  3. Click Add Integration in the top right corner of the integrations page.
  4. Select GitHub Enterprise from the Integration Provider list and click Next.
  5. Choose one of the three ways to connect your GitHub Enterprise account. 

OAuth

Connecting via OAuth requires you to first create a new OAuth application in your GitHub Enterprise account. 

  1. Click your avatar in the top right corner of your Github Enterprise, then click Settings.

  2. Under Personal Settings, click OAuth applications.


  3. Under the Developer applications tab, click Register a new application.


  4. Fill in the Register a new OAuth application form with the following information:


  5.  Click Register application.


  6.  If you wish to add a logo, save this Flow icon (.png below) to your desktop, and drag it into the Drag & drop area.

    A window will popup. Click Set new application image.
  7. Navigate back to the OAuth Apps page in your GitHub account. Copy your and your GitHub's instance base URL into the authorization page in Flow.



    Tip: Make sure you are not blocking pop-ups as you will need to authorize the application.

  8. Click Authorize application.



If your connection was successful you will see the following message:


If you are not able to connect to your account check your Client ID and Client Secret to make sure they are correct and try again. 

To finish up your GitHub Enterprise Integration skip down to the Finishing Up section below. 

Username and Password

  1. Connect to your account using your GitHub Enterprise credentials under the Username/Password tab. Input your credentials and base URL. Click Test connection.


  2. If the connection was successful, you will receive a success message.


    If you receive an Authorization failed error, verify your credentials are correct and try again.

    • user name and/or password are correct


    If you receive a Could not connect to url error, verify the base URL is correct and try again.

    • Base URL is correct


  3. To finish up your GitHub Enterprise integration see the Finishing Up section below.

Access Token

To connect via an access token, use the Access token authentication method. 

  1. In GitHub, navigate to your Personal settings.

  2. Click Developer settings in the left navigation pane

  3. Next, click Personal access tokens, then Generate new token.

  4. Give your token a description in the Note text box, enter the recommended scopes below, and then click Generate token

    In the Select Scopes section, select the scopes below. Flow needs these scopes in order to import and process your repos and projects and to enable webhooks.

    repo (all)

    admin:org

    • read:org

  5. admin:repo_hook (all)

    admin:org_hook

    user

    • read:user

  6. Once you have created your token, copy and paste it into your GitHub Enterprise integration in Flow and click Test connection.

    If the connection was successful you will see the following message:

Finishing Up

  1. Once you have successfully connected to your GitHub Enterprise account, click Next.

  2. On the next screen you will be selecting the services you want turned on for this integration. If you would like to import ticket and pull request data in addition to repo data, then leave all services on. You can turn services “on” and “off” at any time. Click Next.


  3. Name your integration so you can identify the account you connected with. Click Create.


  4. You have successfully created a new GitHub Enterprise integration.


  5. You can begin to import your repos by going to your repo import page. Click the repo import page link. To learn more about managing your new integration settings, see Manage integrations.


Troubleshooting 

If you receive an error message when testing your connection during the setup process, check the following:

  1. If we are unable to connect to your URL:

    1. Verify our IP addresses are allowlisted if you are behind a firewall.

    2. Your domain is accessible outside of your network (public DNS resolution). If your public domain is different from your internal domain, you will need a reverse proxy in place in order for Flow to be able to import and process your data.

    3. A valid  SSL certificate signed by a public CA.

  2. If the authorization failed, check your credentials and try again.

back to top


If you need help, please email support@pluralsight.com for 24/7 assistance.