Troubleshoot GitHub connection and indexing

Overview

This guide helps you fix problems connecting GitHub to Moxie Docs, granting repository access, and getting the first index to run so docs show up in your dashboard. Use it when a repository is missing, the GitHub App was installed but nothing appears, or the index is stuck or not finishing.

Before you start

• You have access to your Moxie workspace and can open the dashboard.
• You are a manager in Moxie if you need to activate repositories. Members can view status but may be directed to repository settings.
• You can sign in to GitHub and, if needed, have permission to install or update the GitHub App on the right repositories.

Repository does not appear in Moxie

You installed the GitHub App or expected to see a repository, but it does not show up in your Moxie dashboard.

1. Confirm you are signed in to the correct GitHub account that owns the repository.
2. Check that the GitHub App was installed on the organization that hosts the repository.
   • If you lack permission to manage apps in GitHub, ask an organization owner to review the installation and repository access.
3. Refresh the Moxie dashboard and look for your repository again. If you are a member, you may see a link to repository settings when activation is required.
4. Verify that the repository was granted access during the GitHub App install. If only “All repositories” or a different subset was selected, update the GitHub App settings in GitHub to include the missing repository.

“Activate Repo” button is disabled or missing

You see the repository in Moxie, but you can’t turn on Docs for it. The “Activate Repo” button may be disabled, or you only see a link to settings.

1. Confirm your Moxie role. Only managers can activate a connected repository.
2. If you are a member, click the link to repository settings shown in the first‑index view to notify a manager or request activation.
3. Managers: Open the repository in Moxie and click “Activate Repo” under the Status header in the first‑index view.
   • If activation is blocked, check that the workspace has an active plan that allows Docs for this repository and that the GitHub App still has access.

First index never started

You activated the repository, but no docs were created and no job appears to be running.

1. Open the repository’s first‑index view and check the Status header.
2. Click “Activate & Queue” to queue the first indexing job.
3. If a job is already queued but hasn’t begun, wait a moment. The page auto‑refreshes while work is queued.
4. If the queue appears idle after refresh, click “Run queued job once” to start the job.
5. If controls are disabled, confirm you are a manager and the repository remains connected in GitHub.

Index is stuck in queued or running

You can see a queued or running job, but it never seems to finish and the page keeps auto‑refreshing with no progress.

1. Stay on the first‑index view and watch for auto‑refresh updates for a few minutes.
2. Cancel and re‑queue the job if a cancel option is shown, then click “Activate & Queue” again.
3. Run the queued job by clicking “Run queued job once.”
4. Recheck GitHub App access for the repository. If access was removed, restore it in GitHub and then re‑queue the job.

Docs did not appear after a completed run

The first index appeared to complete, but you do not see any generated docs in the dashboard collections.

1. Refresh the repository page and browse your collections or search across generated pages.
2. Verify you activated the correct repository and that it contains code or docs to index.
3. Queue another run by clicking “Activate & Queue,” then run it once with “Run queued job once.”
4. If you’re a member and cannot retry, contact a manager to review the first‑index status.

I don’t have permission to proceed

You are blocked by permissions in Moxie or GitHub when trying to activate a repo or start the index.

1. Check your Moxie role in the workspace. Members may be directed to repository settings and cannot activate or run jobs.
2. Ask a Moxie workspace manager to activate the repository or run the job from the first‑index view.
3. Request GitHub organization owner help to install the GitHub App or grant the repository access if you cannot change it.

Still need help

• Recheck: your Moxie role (manager vs. member), GitHub App installation on the correct organization, and that the specific repository is granted access.
• Contact your Moxie workspace admin or manager if you need activation or job controls.
• If the issue persists after these steps, capture the repository name and what you see under the Status header and share it with your workspace admin for review.