GitHub Enterprise setup

Tags: Flow

Overview:

Below is a step-by-step guide on how to connect your GitHub Enterprise account to Flow.  If your repositories are behind a firewall, please whitelist our IPs on 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 that the server is utilizing.

Important: We strongly recommend you use a service account to create this Integration. Please 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, which include repos, 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, all services (repos, PRs, tickets) will be available in Flow except Webhooks. 

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. To learn more about Webhooks, click here. 

OAuth Permissions: Flow only requires read access to your repositories. This permission is needed 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:

A.) OAuth - Connecting via OAuth will require you to create an OAuth application in your GitHub Enterprise account. 

B.) Username/Password - Connecting with your GitHub Enterprise login credentials.

C.) Access Token - This will require you to create an access token in your GitHub Enterprise account. 

1: In order to connect your GitHub Enterprise, you will need to first create a new integration. Starting on your Flow home page, go to the top navigation bar and click Settings. Using the left navigation under Integrations, click Integrations.


 2: Select the Add Integration button in the top right hand corner of you integrations screen.


3: On the following page select GitHub Enterprise from the Integration Provider list and click Next.


4: In this next step you can choose one of the three ways to connect your GitHub Enterprise account. Choose the connection that works best for you. 


A.) OAuth

Connecting via OAuth will require you to first create a new OAuth application in your GitHub Enterprise account. Follow the steps below to get started. 

1: On any page of your GitHub Enterprise, click your avatar in the top right-hand corner, 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.


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

 6b: A window will pop-up, click Set new application image.

7: Navigate back to the OAuth Apps page in your GitHub account. Copy your and into the authorization page in Flow as well as your GitHub’s instance base URL.




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

8: Authorize the application in the pop-up by selecting Authorize application.


9: 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. 

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

B.)Username/Password

1: You can connect to your account using your GitHub Enterprise credentials under the Username/Password tab. Input your credentials and base URL and click Test connection.

Note: GitHub will be deprecating basic authentication in August 2020. We suggest using an alternative authentication method at this time.

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


If you receive the following error when trying to connect your GitHub Enterprise account verify the following and try again:

  • user name and/or password are correct


If you receive the following error when trying to connect your GitHub Enterprise account verify the following and try again:

  • Base URL is correct


3: To finish up your GitHub Enterprise integration skip down to the Finishing Up section below. 

C.) 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 on Personal access tokens then Generate new token.

4: Give your token a description in the Note text box, input 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

admin:repo_hook (all)

admin:org_hook

user

  • read:user

5: 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 are not able to connect to your GitHub Enterprise instance and you receive an error message when testing your connection during the setup process, please check the following and try again:

  1. Could not connect to URL: If we are unable to connect to your URL, please check to ensure that you have:
    A, Whitelisted our IP addresses (if you are behind a firewall)
    B, Your domain is accessible outside of your network (public DNS resolution)

    i, 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.

    C, A valid  SSL certificate signed by a public CA.



2, Authorization Failed: If we were unable to authenticate the connection, please check your credentials and try again. 

back to top


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