Troubleshoot GitHub App and repository access

Overview

Use this guide to fix problems that stop Moxie Docs from connecting to GitHub, syncing repositories, or showing fresh documentation signals. It covers GitHub App install issues, missing or incomplete repository access, and situations where drift cards, PR opportunities, or documentation look stale. Follow the sections in order to verify install, permissions, sync status, and data availability in the Docs dashboard.

Before you start

• You can sign in to Moxie Docs and open the Docs dashboard for your workspace.
• You know who your workspace owner or admin is (they can change workspace settings and manage automation).
• You have access to the GitHub organization or repositories you expect to use with Moxie Docs.

Repository does not appear in Moxie

You installed the GitHub App but a repository you expect to see is missing from the Docs dashboard. This usually means the app was installed for the wrong scope or the repo was not selected during install.

1. Open the Docs dashboard and confirm which repositories are shown.
2. Check the GitHub App installation to confirm the correct organization and repositories are selected.
   • If you manage the GitHub App, open your GitHub organization’s settings and review the app’s installation.
   • Make sure the app is installed on the organization that owns the missing repository.
   • Make sure the specific repository is selected if the app is limited to selected repositories.
3. Refresh Moxie Docs by reopening the Docs dashboard and waiting a few minutes for the list to update.
4. Ask a workspace owner or admin to verify that the repository is allowed in your workspace if it is intentionally filtered.

Repositories show, but docs or code aren’t indexed

You can see the repository in Moxie Docs but no drift cards appear, and PR suggestions look incomplete. This usually means Moxie Docs has not finished its first sync or indexing for that repo.

1. Open the Docs dashboard and go to the PR opportunities section.
2. Confirm whether any cards are grouped under the repository. If none show after first install, allow time for analysis to complete.
3. Check that the repository has recent commits. If there are no recent changes, drift cards may be limited until new code changes occur.
4. Reopen the Docs dashboard after a few minutes to see if cards start to appear.
5. Ask a workspace owner or admin to confirm that automation for that repository is enabled and not paused.

Drift cards don’t appear where you expect them

You expect to see drift findings (e.g., stale docs or undocumented APIs), but the PR opportunities section is empty or missing items.

1. Open the Docs dashboard and locate the PR opportunities section grouped by repository.
2. Filter visually by repository group and check if cards are hidden.
   • Workspace owners and admins can hide low‑value drift findings permanently or for a set time window and undo later.
   • If cards were hidden, ask an owner or admin to unhide them so they appear again.
3. Confirm which drift detectors are enabled for the repository.
   • Ask an owner or admin to review per‑repo automation controls and turn on the detectors you want to use.
4. Reopen the Docs dashboard to refresh the list of cards after changes.

Docs look stale in the Docs dashboard

Pages or summaries in the Docs dashboard don’t reflect recent code changes, or suggestions seem out of date.

1. Reopen the Docs dashboard to trigger a fresh view of current status.
2. Verify that recent pull requests affecting docs were merged in GitHub.
3. Check the PR opportunities section for new cards that highlight stale docs or convention mismatches.
4. Open a card to view details and, if appropriate, open a focused docs pull request to update the content.
5. Confirm that the consolidated guidance comment on related GitHub pull requests has the latest alignment guidance.

Pull request suggestions seem incomplete

Moxie Docs creates focused documentation pull requests with suggested updates and a single deduplicated “convention review” comment. If suggestions seem incomplete, the repository’s automation or detectors may be limited, or the PR description is out of alignment.

1. Open the relevant card in the PR opportunities section and review the suggested changes.
2. Open the GitHub pull request created from the card and read the consolidated, auto‑updating guidance comment.
3. Align the PR description with the guidance so Moxie Docs can refine its suggestions.
4. Ask a workspace owner or admin to adjust per‑repo automation, including which drift detectors are enabled and whether recap comments on PRs are turned on.
5. Recheck the card in the Docs dashboard after a few minutes for updated suggestions.

GitHub App is installed, but access errors persist

You installed the GitHub App, but Moxie Docs still can’t access repositories or data. This often comes from permission mismatches or installing the app on personal scope instead of the organization.

1. Confirm the app is installed on the correct GitHub organization that owns the target repositories.
2. Verify the installation includes all required repositories.
   • If the app is set to selected repositories, add the missing repositories to the installation.
3. Sign out and sign back in to Moxie Docs to refresh your session, then open the Docs dashboard again.
4. Ask a workspace owner or admin to confirm your user has access to the workspace and to the repositories shown in the Docs dashboard.

Cards appear, but you cannot open a focused docs PR

You see drift cards but can’t create the pull request from Moxie Docs.

1. Open the card in the PR opportunities section and review the options presented.
2. Check that you have permission in GitHub to open pull requests in that repository.
3. Ask a workspace owner or admin to confirm per‑repo automation allows creating pull requests from Moxie Docs.
4. Retry opening the focused docs pull request from the card.

Changes were hidden and now you need them back

Findings were hidden earlier and now the dashboard looks empty for a repository.

1. Ask a workspace owner or admin to undo hidden drift findings for the repository.
2. Reopen the Docs dashboard and confirm the PR opportunities section now shows the restored cards.

End‑to‑end sanity check

If multiple steps above did not help, confirm the full flow from install to data in Moxie Docs.

1. Verify the GitHub App is installed on the correct organization and includes the right repositories.
2. Confirm you can see the repository group in the PR opportunities section in the Docs dashboard.
3. Check for at least one recent commit or open pull request touching docs or code that affects docs.
4. Look for cards appearing after analysis completes. If present, open one and create a focused docs pull request.
5. Review the consolidated guidance comment on the GitHub pull request and align the description as suggested.
6. Return to the Docs dashboard and confirm status updates appear after a short delay.

Still need help

• Recheck that the GitHub App is installed on the correct organization and that the needed repositories are selected.
• Confirm a workspace owner or admin has enabled the right drift detectors and has not hidden current findings.
• If problems persist, contact your workspace owner or admin and share what you verified above, including the repository name, the organization, and a link to any related GitHub pull request.