Configuration guide

GitHub Connector

Access knowledge from your GitHub Repositories

Before you begin

Availability depends on your school's enabled tools, provider setup, and account permissions. These settings are managed in the web workspace. A class policy may restrict a feature described here. Some options require a separately licensed feature. The presence of a guide does not unlock that feature.

How it works#

The Github Connector picks up all of the Pull Requests and Issues in a specified repository.

It will index both Open and Closed PRs. This includes the Title and Summary.
It will index Issues and comments both Open and Closed
Includes certain other metadata such as the URL, creator, etc.

Permission Sync Feature#

The GitHub connector supports permission synchronization, which ensures that users can only access documents they have permissions to view in GitHub. When enabled, this feature:

Syncs user permissions from GitHub repositories and organizations
Ensures that users only see search results for repositories they have access to
Maintains consistent access control between GitHub and Nexus

Permission sync is available only on Cloud and the Enterprise Edition of Nexus, and it requires additional token permissions beyond those needed for basic indexing.

⚠️ CRITICAL REQUIREMENT: Public Email Profile#

VERY IMPORTANT: For permission sync to work, users must have their email address publicly visible in their GitHub profile. If a user's email is set to private, they will not get access to any documents through Nexus.

How to make your email public on GitHub#

Log in to GitHub#

Log in to your GitHub account

Access profile settings#

Click on your profile picture in the top-right corner and select **Settings** from the dropdown menu

Navigate to email settings#

In the left sidebar, click on **Emails**

Enable public email#

Scroll down to **Keep my email addresses private** and **uncheck this option**

Configure public profile#

Now go back to the left sidebar and click on **Public profile**

Set public email#

Scroll down to the **Public email** section and select your email address from the dropdown

Save changes#

Click **Update profile** to save the changes

Why is this required?

Nexus uses the public email to match GitHub users with Nexus users for permission synchronization. Without a public email, the system cannot identify which GitHub permissions apply to which Nexus user.

Setting up#

Authorization#

This Connector uses a GitHub Access Token. The required permissions depend on whether you're using the permission sync feature.

Basic Setup (Indexing Only)#

For basic indexing without permission sync:

Review detailed guide#

This guide shows the following steps in detail.

Log in to GitHub#

Access settings#

In the upper right corner, expand your profile and click on Settings

Navigate to developer settings#

On the bottom, go to Developer settings -> Personal access tokens -> Tokens (classic)

Generate new token#

Click on Generate new token

Grant permissions#

Grant the following permissions:

Repository permissions:
repo (Full control of private repositories) - to access PRs and issues

Fine-Grain Access Token Requirements#

If you're using a fine-grain access token instead of a classic token:

Open repository permissions#

    In the token configuration page, go to **Repository permissions**

Add permissions#

    Click **Add permission**, then add the following with **Read access**:

    * **Pull requests** - to access PR data
    * **Metadata** - for repository metadata
    * **Issues** - to access issues and comments
    * **Contents** - to access repository contents

Permission Sync Setup#

Pick the token type you're using:

Fine-grained access token#

Select the organization (resource owner)#

  When creating a **fine-grained** GitHub access token for **permission sync**,
  make sure you select the correct **Resource owner organization** (the GitHub **organization** that owns the
  repositories you want to create the connector for).
  Fine-grained tokens scoped to a personal user account do **not** allow granting **Organization permissions**
  (like **Members**), so permission sync requires selecting an organization as the resource owner.

Add required permissions#

  Add these in the token configuration page using **Repository permissions** -> **Add permission** and
  **Organization permissions** -> **Add permission**:

  

  * **Repository permissions** (Read access): **Administration**, **Issues**, **Metadata**, **Pull requests**
  * **Organization permissions** (Read only): **Administration**, **Members**

Classic token#

Add the org read scope#

  If you're using a **classic** GitHub personal access token (PAT) and want **permission sync**,
  you must also grant:

  * `read:org`

Keep indexing scopes enabled#

  Keep the basic indexing permission enabled as well:

  * `repo` (Full control of private repositories) - to access PRs and issues

Token Configuration#

Set expiration time#

Set any expiration time. A new token will have to be provided to Nexus to continue updating the Nexus index once this one expires.

Verify permissions#

Important: If you plan to use permission sync, ensure all the above permissions are granted when creating the token.

Indexing#

Navigate to connector#

Navigate to the Admin Panel and select the GitHub Connector

Configure connector#

For https://github.com/onyx-dot-app/onyx, it would look like:

Before using this source with students#

Start with approved course material. Check which documents the connector can retrieve and how it maps source permissions. Test with a student account and a teacher account before widening access. A successful sync does not prove that the intended class boundary is correct.

Use source troubleshooting when a document is missing or visible to the wrong audience.