How to integrate GitHub with Sapho version 4.3 or greater

Audience: Developers building Sapho micro apps

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, and
  • you are on “What is the connection information?” screen.

1: Enter the name of the GitHub organization

For example saphocom.
ghp1.png

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 sample-data-ghp.

ghp2.png

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 Repository Names 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 the Number of Months of Data to Load (see step 6).

3: Enter a personal access token

  • Since GitHub Public only connects 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.ghp3.png
  • Enter a name for the new token (e.g. sapho).
  • Check the following scopes: repo, admin:org, and user.
  • Click Generate token.gh4.png
  • Copy the generated token and paste it in a secure place for future reference.ghp5.png
  • Also paste it in Sapho in the Token field.

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: https://git.acme.com.

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

During testing, our Sapho engineers determined that the connector works best with only one connection, which is the default value. You can adjust it, but keep in mind that the connector might have an unstable behavior. (GitHub might be overloaded with requests and even deny responding to Sapho.)

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 downloading data depending on how much data there is in those repositories.

Click Next and finish the creation of the connector.

 

Troubleshooting

The section describes some possible solutions for common issues.

Sapho is unable to connect to GitHub (cloud)

  • Check here to make sure that GitHub is not currently down. If it is, all you can do is wait.
  • If Sapho Server runs on premises behind a proxy, configure Sapho to work with your proxy server as described here.
  • If the connector log shows "com.sapho.services.spi.ServiceException: 404: Not Found" error, you might be trying to download data from a repository that doesn't exist or from one to which you don't have access (more here). Make sure you 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.

 

Sapho is unable to connect to GitHub Enterprise (on-premises)

  • If Sapho Server runs in a private cloud (e.g. AWS) and GitHub Enterprise is behind a corporate firewall, whitelist Sapho Server’s IP address in your firewall so it can connect to the GitHub server.
  • If the connector log shows "com.sapho.services.spi.ServiceException: 404: Not Found" error, you might be trying to download data from a repository that doesn't exist or from one to which you don't have access (more here). Make sure you 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.

If you are still having problems with the GitHub Public connector, contact Sapho support at support@sapho.com.