A step-by-step guide to connecting GitHub and adding repository knowledge to Sphinx.
Connect your GitHub account, choose a repository, and tell Sphinx what to learn from it. A repository is a collection of files stored in GitHub. An ingest is the process of reading those files and turning them into knowledge in Sphinx.
A connector is the saved connection between Sphinx and GitHub. You will create one, allow access in GitHub, and then sign in to it.
1
Open Connectors
In Sphinx, click Settings at the bottom left.Check that the correct Workspace is selected, then click Connectors.
Settings → Connectors
2
Choose GitHub
Click New connector.Under Documents & repositories, click GitHub.
Choose the GitHub card.
3
Name your connection
In Connector name, enter a name you will recognize, such as GitHub documentation demo.Click Connect GitHub. GitHub opens in another tab. Keep the Sphinx tab open.
Enter a name, then click Connect GitHub.
4
Choose the repository in GitHub
Sign in to GitHub if asked. Choose the account or company that owns your repository.Select Only select repositories, open Select repositories, and choose the repository you want Sphinx to read. Our example is sphinx-ml/docs.Review the permissions, then click Install. If the app is already installed, you may see Update access instead.
Choose your repository. This example shows an app that is already installed.
If GitHub shows Request or says an organization owner must complete this action, ask the person who manages your company’s GitHub account to finish this step. See GitHub’s installation help for details.
5
Return to Sphinx and sign in with GitHub
Return to your Sphinx connector tab. Refresh the page if needed.Under Authentication, click Sign in with GitHub. Follow GitHub’s prompts to authorize the connection.When you see Authentication successful. You can close this tab., close that tab and return to Sphinx.
If Sign in with GitHub is greyed out, finish Install GitHub App first. Installation and sign-in are two separate steps.
6
Check that you are connected
Your connector should now show Manage GitHub App and Reconnect GitHub. Refresh the page if those buttons have not updated.You are ready to set up the ingest.
These buttons show that installation and sign-in are complete.
In the same Sphinx workspace, click Ingest in the left sidebar.Click New Ingest at the top right.
Ingest → New Ingest
2
Choose Git Repository
Scroll down to Experimental and click Git Repository.
Find Git Repository near the bottom of the page.
3
Choose your connection and repository
In GitHub connector, select your saved GitHub connection.In Repository, choose the repository you want to add. For this example, choose sphinx-ml/docs.Choose the connection you named earlier: GitHub documentation demo in this example.
4
Write a detailed focus prompt
In Focus prompt, explain what you want Sphinx to learn and give it the context it needs to understand your repository.
Take time to write a detailed, specific prompt. A high-quality focus prompt helps Sphinx find the right information and preserve the details your team needs. Include useful context and concrete questions, rather than just asking it to “summarize the repository.”
You do not need to write code. In plain language, include:
Your goal: Who will use this knowledge, and what should it help them do?
Where to look: Name important topics, folders, or files if you know them.
Context: Explain unfamiliar terms and identify which information is current or most reliable.
Details to keep: Call out rules, calculations, exceptions, dependencies, or setup steps that matter.
Questions to answer: Give a few real questions you want Sphinx to be able to answer afterward.
For the documentation repository in this guide, a detailed prompt could look like this:
Help customer-facing teammates explain how customers connect Claudeand ChatGPT to Sphinx. The knowledge should support someone walkinga non-technical customer through setup.Start with the guides in claude/, claude-code-cli/,claude-desktop/, and chatgpt-desktop/. Follow related guides whenthey explain a prerequisite or a step in the same setup process.Keep the instructions for each client separate. Explain thedifference between connecting to Sphinx MCP and using the SphinxLLM Gateway, based on the repository's guides.Preserve prerequisites, exact button names, configuration values,sign-in steps, actions that need an administrator, and how userscheck that the connection worked. Include documented troubleshooting.If guides disagree or leave a step unclear, call that out insteadof guessing.The knowledge should answer:- What does a customer need before starting each setup?- What should they click and enter, in order?- Which steps need help from an administrator?- How do they confirm that setup worked?
Example for an internal analytics dashboard repository
Use this example if your team builds internal analytics dashboards. Add the dashboard names, business topics, and folders that matter to your team.
This repository contains our internal analytics dashboards. Helpour teammates understand what each dashboard shows, how its numbersare calculated, and how to use them to answer business questions.We want Sphinx's knowledge to reflect the repository as it evolves.Focus on dashboard definitions, charts, queries, data models, andrelated documentation. Follow supporting code, configuration, andtests when they explain a calculation or business rule.For each dashboard, explain its purpose, intended audience, andthe business questions it answers. Preserve chart and metric namesso teammates can match the explanation to what they see on screen.For each metric, explain its business meaning, calculation, sourcetables, filters, exclusions, and time period. Explain how tablesconnect, what one row represents, and how dates and time zonesaffect the result. Include these details when the repositoryprovides them; flag anything unclear instead of guessing.Explain how dashboard filters, default selections, and drill-downschange the numbers. Include documented refresh schedules, datadelays, limitations, and reasons similar charts may disagree.On each ingest, use the current repository definitions. Capturenew dashboards and changed calculations, filters, or businessrules. Identify deprecated dashboards and metrics where therepository marks them as such. Include relevant file paths soteammates can find the source of an explanation.The knowledge should answer:- Which dashboard should I use for my business question?- What does this metric mean, and how is it calculated?- What data is included or excluded?- How do filters and date ranges affect the result?- How fresh is the data, and what limitations should I know?
Adapt these examples to your repository. Specificity matters more than length: include the context you know and the details you need, without adding unrelated instructions. Explain the business meaning you want to capture, rather than asking for a file-by-file code summary.
Choose a connector and repository, then enter your detailed focus prompt. You can scroll within the prompt to review it.
5
Create the ingest
Check that the repository and focus prompt are correct, then click Create ingest once.Sphinx opens a page where you can follow its progress. You can also find the job later under Ingest.When Review Changes appears, click it to read the proposed knowledge before accepting it.
Go to Settings → Connectors and open your connector.Click Install GitHub App to finish installation, or Sign in with GitHub to finish signing in. You do not need to create another connector.
GitHub says I need an organization owner
Ask the person who manages your company’s GitHub account to complete the app setup for your repository. Return to Sphinx afterward and refresh the connector page.If the app already has access but Sphinx still shows Install GitHub App, ask the Sphinx team for help connecting that existing installation.
My repository is missing
Check that you selected the right GitHub connector and signed in with an account that can access the repository.Open the connector and use Manage GitHub App to check that your repository is included. Ask your GitHub administrator for help if you cannot change this. Then reload the ingest page and select the connector again.
My connector is missing
Check the Workspace in Settings. Use the same workspace where you created the connector.
Git Repository is missing
Ask the Sphinx team to enable Git ingest for your workspace. Include your workspace’s name.
Create ingest is greyed out
Make sure you selected a connected GitHub connector, chose a Repository, and entered a Focus prompt.
Which version of my files will Sphinx read?
Sphinx reads the repository’s default branch—the version GitHub normally shows when you open the repository. There is no branch selector on the ingest page.
I need help with an ingest
Share the job ID, repository name, and any error message with the Sphinx team. If knowledge is missing, give one example of what you expected Sphinx to learn.
