Docs, for Moxie Docs

Troubleshoot GitHub PRs

4 min readUpdated

Overview

Use this guide to fix problems with documentation pull requests created by Moxie Docs on your connected GitHub repository. It covers missing PRs, PRs that fail Checks, and PRs that do not follow your repository rules or Moxie settings. Work through the section that matches what you see in GitHub or in the Moxie dashboard.

Before you start

  • You have access to the Moxie workspace that is linked to your GitHub repository.
  • You can open the repository on GitHub and view pull requests and Checks.
  • You have permission to change Moxie settings in the workspace dashboard, or you can ask a workspace admin to do it.

Docs PR never appears in GitHub

You expect a docs-only pull request from Moxie, but nothing shows up in the repository on GitHub.

  1. Open the Moxie dashboard and go to the connected repository.
    • Look for a status banner or recent activity showing the last sync.
  2. Confirm the repository is connected.
    • If the repo is missing, reconnect it from the workspace’s repositories list.
  3. Check conservative or suggest mode settings.
    • If the repo is not fully armed, Moxie may hold changes or only surface suggestions without opening a PR.
  4. Review recent runs.
    • If there are no eligible documentation changes, Moxie will not open a new PR.
  5. Verify GitHub access.
    • Make sure you can see the repo on GitHub and that the Moxie connection still has access to it via your workspace.

Docs PR appears but has no changes

A pull request opens but the Files changed tab is empty or shows trivial metadata only.

  1. Open the PR on GitHub and check the “Files changed” tab.
  2. Compare with the latest code changes in the default branch.
    • If there were no documentation-impacting updates, the PR may be empty by design.
  3. Confirm Moxie settings for suggest or conservative mode.
    • In conservative mode, Moxie may submit minimal updates until the repo is fully armed.
  4. Close the PR if it is not needed and monitor the next sync for future changes.

GitHub Checks fail on the docs PR

The PR shows failed Checks added by Moxie or other required Checks in your repository.

  1. Open the PR on GitHub and select the “Checks” tab.
  2. Read the advisory comments from Moxie in the Conversation tab.
    • Moxie adds guidance on what failed and why.
  3. Follow the remediation notes in the failed Check.
    • If the Check is from your repo’s rules (for example, required reviews), complete those requirements.
  4. Re-run Checks if available by clicking “Re-run all checks” on GitHub.
  5. Adjust Moxie settings only if needed.
    • If your repo is not fully armed, consider keeping conservative or suggest mode until failures are resolved.

PR does not follow repository rules

The PR is blocked by branch protection, required reviewers, or other repository policies.

  1. Open the PR on GitHub and review the “Merge” box for required conditions.
  2. Complete required reviews or status Checks listed in the PR.
  3. Confirm that Moxie is set to respect your policies.
    • Moxie aligns with GitHub and does not bypass your rules; it will wait until conditions are met.
  4. Coordinate with your repo maintainers to update rules only if appropriate for docs-only changes.

Moxie comments appear, but no PR is opened

You see advisory comments from Moxie or activity in the dashboard, but no corresponding PR exists.

  1. Check the Moxie dashboard activity for the repository.
    • In suggest mode, Moxie may leave guidance without opening a PR.
  2. Switch to a more permissive mode if appropriate for your team.
    • Ask a workspace admin to adjust from suggest to conservative or fully armed when you are ready for PRs.
  3. Trigger a new sync by saving relevant settings or waiting for the next automated run.

Docs PR is stuck and not updating

A PR exists but stops receiving updates even though the codebase changed.

  1. Open the PR and check the latest commit time.
  2. Look in the Moxie dashboard for recent runs on the repository.
    • If a run failed, Moxie will not update the PR until the next successful run.
  3. Close the stale PR if appropriate and allow Moxie to open a fresh one on the next run.
  4. Verify that the repository connection is healthy and that you still have access on GitHub.

Approved pages are not publishing to the knowledge base

You merged a docs PR, but you do not see the updated pages where your team searches or on the public knowledge base.

  1. Open the Moxie dashboard and go to the repository’s publish settings.
  2. Confirm that publishing is enabled for the workspace or the public knowledge base.
  3. Check that the PR was merged into the branch Moxie uses for published pages.
  4. Wait for the next indexing cycle, then search again in your team’s search.

Still need help

  • Recheck repository access, Moxie mode (suggest, conservative, fully armed), and the latest run status in the dashboard.
  • If issues continue, contact your workspace admin to review permissions and settings or to reconnect the GitHub repository.

Was this page helpful?

Let us know if you found what you were looking for.

Related articles

GuidesBilling, trial, or access issuesThis guide helps you fix problems starting a trial, completing a subscription through Stri
GuidesConfigure PR automation and detectorsUse Moxie Docs’ repository automation to keep docs PRs consistent, tune drift detectors, a
GuidesFix missing or outdated docs in the dashboardUse this guide if documentation collections look empty, out of date, or a collection you e