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 Onyx
Permission sync is available only on Cloud and the Enterprise Edition of Onyx,
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 Onyx.
How to make your email public on GitHub
How to make your email public on GitHub
1
Log in to GitHub
Log in to your GitHub account
2
Access profile settings
Click on your profile picture in the top-right corner and select Settings from the dropdown menu
3
Navigate to email settings
In the left sidebar, click on Emails
4
Enable public email
Scroll down to Keep my email addresses private and uncheck this option
5
Configure public profile
Now go back to the left sidebar and click on Public profile
6
Set public email
Scroll down to the Public email section and select your email address from the dropdown
7
Save changes
Click Update profile to save the changes
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:1
Review detailed guide
This
guide
shows the following steps in detail.
2
Log in to GitHub
Log in to GitHub.
3
Access settings
In the upper right corner, expand your profile and click on Settings
4
Navigate to developer settings
On the bottom, go to Developer settings -> Personal access tokens -> Tokens (classic)
5
Generate new token
Click on Generate new token
6
Grant permissions
Grant the following permissions:
- Repository permissions:
repo(Full control of private repositories) - to access PRs and issues
Fine-Grain Access Token Requirements
Fine-Grain Access Token Requirements
If you’re using a fine-grain access token instead of a classic token:
1
Open repository permissions
In the token configuration page, go to Repository permissions
2
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
- Classic token
1
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.
2
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
Token Configuration
1
Set expiration time
Set any expiration time.
A new token will have to be provided to Onyx to continue updating the Onyx index once this one expires.
2
Verify permissions
Important: If you plan to use permission sync,
ensure all the above permissions are granted when creating the token.
Indexing
1
Navigate to connector
Navigate to the Admin Panel and select the GitHub Connector
2
Configure connector
For https://github.com/onyx-dot-app/onyx, it would look like:
