GitHub Integration Guide

Overview

By integrating GitHub with Common Room you can see contributors, comments, pull requests, repo stars, repo forks, issues, discussions, and top programming languages for members of your community. Common Room creates a profile for every contributor in your GitHub community and an activity for each issue, pull request, comment, or starred repo.

Setup

Before integrating GitHub, login to the GitHub account you want to integrate into Common Room. Once you're logged in, open the signals page in Common Room, and select GitHub.

1. Select GitHub from the list of signals.
2. Connect GitHub. When you connect GitHub, Common Room will surface activity and insights across pull requests, issues, contributors, starred repos, and comments.

There are two options for connecting your Github Signal:

1. Direct authentication if you have admin access
   1. Authenticate your GitHub and select repos. Select "I have admin access or approval". The GitHub integration with Common Room requires admin access or approval. If you don't have admin access to your GitHub account, an email request will be sent to your admin to approve the integration.
   2. Install and authorize Common Room. When you install and authorize Common Room to access your GitHub repository, you can select between some or all of your public repos.
      

      If you select to grant Common Room access to "all repos," Common Room will automatically begin tracking all current and future public repos. If you choose "some repos," you will need to manually select the public repos you'd like tracked. If you wanted to have a new public repo tracked in the future, you'd need to add this in your GitHub signal settings at that time.

   3. Begin data import. After authorizing Common Room, your data will start to import. Importing your data may take up to a few hours, and we’ll email you when everything’s ready. In the meantime, you can take a peek into Common Room. The charts and functionality may be a little empty to start but will populate as your data flows in.
      

      For large GitHub repos, data imports may take several days to complete due to GitHub API restrictions. You'll receive an email as soon as the import is ready.

1. Using a GitHub API token if you do not have admin access
   1. Obtain a GitHub API key. Follow the directions in the setup screen to create an API key in GitHub and paste it into the text box for verification.
   2. Select the desired repositories. Enter the GitHub organization that hosts the repos of interest and use the dropdown to select the specific repos you would like to access.
   3. Begin data import. After selecting the repos, your data will start to import. Importing your data may take up to a few hours, and we’ll email you when everything’s ready. In the meantime, you can take a peek into Common Room. The charts and functionality may be a little empty to start but will populate as your data flows in.
      

      When connecting repos using a GitHub API key, the following limits are in place to help keep API calls within quota limits. Please contact us if you would like to discuss updating the limits.

      • 12k star limit for repos
      • 10 repos connected per API key based Github signal
      • 4 API key based GitHub signals

Technical details

The GitHub integration is available on all plans.

Contacts and Activity

Contacts are created from users who have created or commented on an issue, pull request, or discussion, and from users who have starred any repos.

When connecting to GitHub, you can configure which repositories you’d like to import. Within your specified repositories, Common Room will create members and activities for every GitHub user who:

• Stars a repository
• Forks a repository
• Creates or comments on an issue
• Creates, closes, merges, or comments on a pull request
• Merges a commit
• Posts or replies in a Discussion

Import history

Once you configure your GitHub integration, Common Room will import activity history from the repositories you’ve chosen. For admin authenticated signals, we will pull in all history and for API token based signals, we will pull 6 months worth of history. Imports may take some time depending on the size of the repositories.

Sync frequency

Once the integration is configured, Common Room will automatically import new activity within a few minutes of it occurring on GitHub.

Obtaining a GitHub API Key

When setting up an API key based signal, please follow the instructions below:

1. Log into your personal GitHub account and go to https://github.com/settings/tokens/new
2. Create a new personal access token (classic) with the following parameters:
   • Note: "CR Imports"
   • Expiration: No expiration
   • Select scopes: Check the boxes for "read:org," "read:user," and "user:email."
   • Click "generate token" and copy the resulting token (starts with “ghp_“)

FAQ

When I connect to all GitHub repositories, does this include both public and private repos?

Common Room only ingests information from public repos, regardless of the option you choose. Private repo information will never appear in Common Room.

How can I sync additional GitHub repositories to Common Room?

In Common Room, open Settings → Signals → GitHub. If you want to add a new signal, select the "Add another signal" button. If you want to edit the list of repositories for an existing signal, select the "Update repositories" button next to the desired signal.

If a Contact unstars a repo, will this appear in their activity?

No. If a Contact stars a repo, this activity will appear in their profile. However, if a Contact un-stars a repo, the activity and history of them starring it will be removed from their profile.

Why is there a difference between connecting an owned vs. unowned repo in the platform?

Owners of GitHub repos can grant access with OAuth, which is much more secure and easy to set up than exchanging API keys. However, if you want to listen to a repo that you don't own, you can't OAuth to it (because the OAuth protocol validates access permissions). In these cases, we use an API key, which allows access to the repo and related info without utilizing any global rate limits, helping us keep your data as fresh as possible using the key provided (as opposed to using a shared key, which would hit rate limits and not let us ingest as fast as we can with a unique key). Note that when pulling in unowned repos via API key, new repos must be explicitly added as they are not not automatically ingested.