Troubleshoot GitHub App and repo access

Overview Use this guide to fix common issues with the Moxie GitHub App and repository access. It covers missing repositories, stale or incomplete indexing, and documentation pull requests (PRs) that aren’t posting.

Before you start

• You need access to your Moxie Docs workspace.
• You need permission in GitHub to install apps and grant repository access for the Moxie GitHub App.

1. You can’t see a repository in Moxie If a repo doesn’t appear in pickers or in your workspace:

1. Check your GitHub sign-in:
   • In Moxie, go to /auth/github and complete GitHub sign-in. Return to Moxie when GitHub confirms authorization.
2. Confirm the Moxie GitHub App is installed:
   • In Moxie, open Dashboard setup/onboarding. Follow the prompt to Install Moxie GitHub App.
   • In GitHub, when asked where to install, select your organization or user account.
3. Grant repository access during install:
   • On the GitHub “Repository access” screen, choose All repositories to allow new repos automatically, or Only select repositories and pick the ones you need in Moxie.
   • Save.
4. Refresh repository pickers in Moxie:
   • In Account → Repository settings, open the repository picker and click Refresh if available, then select your repo.
5. If the repo is private or recently created:
   • Repeat step 3 and make sure that repo is included. If you chose Only select repositories, add the new repo and save.

2. Indexing feels stale or incomplete If search, Q&A, or the changelog seems out of date:

1. Verify the repo is linked:
   • In Account → Repository settings, confirm the repository is listed and enabled for your workspace.
2. Confirm the app has access:
   • In GitHub’s installed apps for your org/account, open Moxie GitHub App and make sure the repository still has access.
3. Trigger a fresh sync from Moxie:
   • Open the Docs dashboard. If you see a sync banner or refresh option for the repository, use it.
   • Return after a few minutes and try search or Q&A again.
4. Check ignored content settings:
   • In Account → Repository settings, review any ignore or filtering choices. If you’ve excluded large folders or file types, indexing won’t include them.
5. Reconnect GitHub if authorization changed:
   • Visit /auth/github and re-authorize if prompted. Then repeat step 3.

3. Documentation PRs aren’t posting If you expect doc updates but no PRs appear:

1. Confirm detectors are enabled:
   • Go to Account → Repository automation.
   • Make sure relevant detector checkboxes are on (for example: stale docs, thin docs, orphaned docs, undocumented APIs, convention mismatches).
2. Review PR opportunities in the Docs dashboard:
   • Open the Docs dashboard and find PR opportunities cards.
   • Use the overflow actions to open or propose the change if it hasn’t been created automatically.
3. Check repo permissions for PRs and comments:
   • In GitHub, ensure the Moxie GitHub App has Write access to the repository so it can open PRs and leave comments.
4. Look for muted or dismissed findings:
   • In the Docs dashboard, confirm the item isn’t muted or dismissed. Unmute to allow a PR to be created.
5. Reconnect GitHub authorization:
   • Visit /auth/github and complete sign-in if requested.
   • Return to the Docs dashboard and re-check PR opportunities.

4. Some repos work, others don’t If only a few repositories fail:

1. Compare app access per repo:
   • In GitHub, open the Moxie GitHub App installation and confirm each affected repository is selected.
2. Align automation settings:
   • In Account → Repository automation, make sure detectors are enabled for the affected repos the same way as the working ones.
3. Re-pick the repository in Moxie:
   • In Account → Repository settings, remove and re-add the affected repository. Then check the Docs dashboard for fresh activity.

5. You changed GitHub org or repo names If you renamed or transferred a repository:

1. Revisit the app installation:
   • In GitHub, open the Moxie GitHub App and confirm access to the renamed or transferred repository.
2. Update selection in Moxie:
   • In Account → Repository settings, re-select the repository under its new name.
3. Run a fresh sync from the Docs dashboard and verify search/Q&A and PR opportunities.

6. You want Moxie to ignore certain changes If you see noisy suggestions:

1. Open Account → Repository automation.
2. Turn off detector types you don’t want for that repository.
3. In the Docs dashboard, use overflow actions to dismiss or mute specific findings you don’t want surfaced again.

Still need help?

• Recheck /auth/github to ensure your session is current.
• Confirm the Moxie GitHub App is installed on the correct GitHub org or user and has the right repositories selected.
• Make sure you have sufficient GitHub permissions to grant access and allow PRs. If issues continue, contact your workspace admin to review GitHub app access and repository settings.