Connect repositories via the GitHub App

Overview Connect your GitHub repositories to Moxie Docs so the app can index your codebase, keep docs fresh, and open documentation pull requests when code changes. This guide walks you through installing the Moxie GitHub App, choosing repositories, managing permissions, and checking indexing status.

Before you start

• You need a Moxie Docs workspace.
• You need a GitHub account with permission to install apps for the repositories you want to connect. If you don’t have that permission, ask an organization owner or a repo admin to complete these steps.

1. Start the GitHub App installation

1. Sign in to Moxie Docs and open your workspace.
2. Go to Settings > Repositories.
3. Select Connect with GitHub. This sends you to GitHub to install the Moxie GitHub App at /auth/github.

2. Choose where to install the app

1. On GitHub, pick the account or organization that owns the repositories you want to connect.
2. Under Repository access, choose:
   • All repositories to give Moxie access to every current and future repo in that account, or
   • Only select repositories to pick specific repos now.
3. Select Install.

Tip: If you manage multiple orgs, repeat the installation for each org that has repos you want to connect.

3. Select repositories in Moxie

1. After installation, GitHub returns you to Moxie Docs.
2. In Settings > Repositories, open Add repositories.
3. Use the repository picker to select one or more repos you want Moxie to index.
4. Select Add to workspace.

4. Manage permissions later (add or remove repos)

• To add more repos: Go to Settings > Repositories > Add repositories and select additional repos.
• To remove a repo from Moxie: In Settings > Repositories, find the repo and select Remove from workspace. This stops indexing and documentation updates for that repo.
• To change app access on GitHub (for example, switch from “Only select repositories” to “All repositories”):
  1. In GitHub, open Settings > Applications > Installed GitHub Apps.
  2. Select Moxie Docs.
  3. Update Repository access and save. Return to Moxie and use Add repositories to link any newly allowed repos.

5. Review required access The Moxie GitHub App uses the permissions you approve to:

• Read code to index your repository and generate documentation.
• Read and write pull requests to comment, open documentation PRs, and keep them updated. If you restrict repository access, Moxie works only for the repos you grant.

6. Verify indexing status for each repository

1. In Moxie Docs, open Settings > Repositories.
2. Check the Status column next to each repo:
   • Indexing: Moxie is scanning the repo. You can leave this page; indexing continues in the background.
   • Ready: Indexing is complete. The repo is available in your docs workspace (search, Q&A, and changelog).
   • Action needed: Hover or open the repo row to see what to fix (for example, missing permissions). Follow the prompt, then select Retry.
3. Select a repo name to open its details and view the last indexed time.

FAQs

• Can I connect private repositories? Yes. Install the app and select the private repos you want. Moxie only accesses the repos you authorize.
• Do I need to re-install for each repository? No. Install once per GitHub account or organization, then use Add repositories in Moxie to link specific repos.
• What if I don’t see a repository in the picker? Confirm the app is installed on the correct GitHub account/org and that the repository is included in the app’s Repository access. Update access on GitHub, then return to Moxie and try Add repositories again.

Next steps

• Explore your docs workspace: Use Search and Q&A to browse indexed content.
• Tune automation: In your workspace, adjust what to flag or ignore so documentation PRs match your team’s conventions.
• Give feedback on results: Your input improves suggestions and documentation updates over time.