How to set up the GitHub Public connector in Sapho
This tutorial assumes that:
- you are logged in Sapho Builder (Admin)
- you have started Add GitHub Public Connector or Add GitHub Public Micro App wizard
- you are on “What is the connection information?” screen.
Step 1: Enter the name of the GitHub organization
Step 2: Enter the name of the public repositories you would like to download
If you would like to download just one repository from the specified organization, simply enter its name, for example
If you would like to download more repositories from the specified organization, enter their names separated by a comma, for example
sample-data-ghp, features, community, examples.
If you would like to download all repositories from the specified organization, leave the Repository Names field blank. Please note that if you choose this option, the connector might need to run for a long time to download all the data. To shorten the time, we advise to apply a load filter by setting a Number of Months of Data to Load (see step 6).
Step 3: Enter a personal access token
Since GitHub Public connects only to public repositories, the Token field is optional. However, we recommend entering a personal access token in order to increase the number of hourly API requests our connector will be allowed to do. To generate a security token, go here. Log in GitHub with your account credentials and click Generate new token.
Enter a name for the new token (e.g. sapho). Check the following scopes: repo, admin:org, and user. And click Generate token.
Copy your token and paste it in a secure place for later reference.
Also paste it in Sapho in the Token field.
Step 4: Enter the URL of the GitHub Enterprise instance
If you are connecting to an organization hosted in the GitHub cloud, leave this field blank. However, if you have a GitHub Enterprise instance, please insert the root URL of your GitHub server (i.e. the path you use to access GitHub in your browser). Example:
Step 5: Set the Max Number of Connections
The Max Number of Connections field is used to set how many parallel threads the connector should use to download data. The reason why it's defaulted to 1 is because our Sapho engineers played with it and this way the connector worked best. You might try playing with it, too. However, keep in mind that the connector might have an unstable behavior (GitHub might be overloaded with requests and even deny responding to Sapho).
This also depends on your connectivity to GitHub. If you have a slow connection to GitHub, you can try to use more parallel connections. If you have a fast connection, you should use less connections, otherwise GitHub will block Sapho for sending too many requests.
Step 6: Set the Number of Months of Data to Load
Enter a number for how many months of data you would like the connector to retrieve. The default is 3 months. If left as it is, the connector will load GitHub issues and pull requests created or updated during the last 3 months.
If you would like to download all the data from the specified repositories, set this field to 0. However, be aware that the connector will need a longer time to finish the data download depending on how much data there is in those repositories.
Click Next and finish the creation of the connector.
This section will describe a number of possible connectivity blockers. Follow the suggested solutions or contact firstname.lastname@example.org.
I. General Issues
Possible issue: You are not able to connect to GitHub and in the logs there is the following error - "com.sapho.services.spi.ServiceException: 404: Not Found".
Cause: You are either trying to download data from a repository that doesn't exist or from one to which you don't have access to. See more here.
Solution: Check whether you have entered the correct organization name and repository name(s) on the connector configuration form. Also make sure that you are trying to download data from a public repository. If you're trying to access a private repository, you need to use the other GitHub connector in Sapho.
II. Issues specific to when connecting to GitHub
Possible issue #1: If Sapho Server runs on premises behind a proxy, it might not be able to connect to the GitHub cloud.
Solution: Configure Sapho to work with your proxy server as described here.
Possible issue #2: GitHub is down.
Solution: Check here if GitHub is down. If yes, all you can do is to wait.
III. Issues specific to when connecting to GitHub Enterprise (on-premises)
Possible issue: If Sapho Server runs in a private cloud (e.g. AWS) and GitHub Enterprise is behind a corporate firewall, Sapho might not be able to connect to it.
Solution: Whitelist Sapho Server’s IP address in your firewall so it can connect to the GitHub server.