Troubleshoot GitHub connection and indexing

This guide helps you fix common problems connecting a GitHub repository to Moxie Docs and getting it indexed. By the end, you’ll have your repo connected, permissions set, and content loading in the Knowledgebase.

Before you start

• Confirm you can sign in to both Moxie Docs and GitHub.
• Make sure you have permission to install GitHub Apps for the target repository or organization.

Fix GitHub App install or connection issues

If the GitHub App doesn’t install or your repo doesn’t show up during setup, follow these steps.

1. Start in the Moxie dashboard and choose Connect a repository.
2. Select GitHub when prompted and Continue to start GitHub OAuth.
3. Sign in to GitHub (if asked) with the account that has access to the repository.
4. Review the GitHub App install screen:
   • Choose the correct organization or personal account.
   • Select Only select repositories and pick the repo you want, or choose All repositories if appropriate.
   • Click Install (or Update if you’re changing the selection).
5. Back in Moxie, select the repository you just authorized and Confirm.

If the repository still doesn’t appear:

• Ensure you installed the App on the right GitHub account or organization.
• If you chose “Only select repositories,” edit the installation in GitHub and add the missing repository, then return to Moxie and refresh the list.
• Sign out and back in to Moxie using the same GitHub account you used for the installation.

Resolve permission problems

Moxie needs access through the GitHub App to index code, discover docs, and open pull requests.

• If indexing never starts, check that the App is installed for the exact repository you selected.
• If Moxie can’t open pull requests, verify the App still has access to that repository and that branch protections allow PRs from Apps.
• If teammates can’t see the repo in your workspace, confirm they’re in the same workspace and that the repo is connected there.

How to update permissions

1. Open GitHub and go to Settings for your organization or profile.
2. Click Installed GitHub Apps and Open the Moxie Docs App.
3. Click Configure and either:
   • Switch to All repositories, or
   • Add the specific repositories you want Moxie to access.
4. Save your changes, then return to Moxie and refresh the repository list.

Troubleshoot indexing and docs loading

After connecting a repo, Moxie indexes files and loads recognized documentation so search, the reader, and generation flows have content.

Indexing hasn’t started

1. Go to Dashboard → Knowledgebase.
2. Check for the repository under Files, Collections, or Health Map.
3. If you don’t see it, refresh the page. If it still doesn’t appear, reconnect the repo from the dashboard and complete the GitHub App steps again.

Indexing seems stalled

1. Open Dashboard → Knowledgebase → Health Map.
2. Look for a status indicator. If you see partial results, give it a few minutes and refresh.
3. If there’s no change after a reasonable wait, disconnect and reconnect the repository from the dashboard, then repeat the install confirmation.

Docs aren’t showing in the reader or search

• Check Files or Collections to confirm recognized docs were attached. If no docs appear, the repo may not include supported doc files.
• If the repo is large, wait a bit longer and refresh; indexing includes sampling source files and loading document bodies.
• If content is unexpectedly missing, confirm the files aren’t excluded by your repository’s ignore rules, then retry indexing by reconnecting the repo.

Fix “Ask this codebase” not returning results

• Make sure indexing has completed by checking the Health Map.
• Confirm recognized docs are visible under Files or Collections.
• If results are thin, wait a few minutes and try again after the next indexing pass completes.

Pull request automation issues

• If you don’t see PRs for doc updates or removals, verify the App still has access to the repository and branches you use.
• Review your team’s branch and PR settings in GitHub to ensure PRs from installed Apps are allowed.
• In Moxie, confirm you’ve connected the correct repository in the correct workspace and plan scope for automation.

When to reconnect the repository

Reconnect if you changed GitHub App permissions, moved the repository between orgs, or indexing hasn’t updated after waiting.

1. Open the Moxie dashboard and go to your connected repository.
2. Click the option to Disconnect or Remove the connection.
3. Reconnect the repository and repeat the GitHub App authorization steps.
4. Return to Knowledgebase and refresh to monitor indexing.

Still need help?

• Try the steps above in order: verify installation, update permissions, check Knowledgebase status, and reconnect.
• If problems continue, contact your workspace admin to confirm access, or reach out to Moxie Support with your workspace name, repository name, and a screenshot of the GitHub App configuration screen.