Troubleshoot GitHub PRs

Overview

This guide helps you resolve problems when Moxie Docs cannot create or update a pull request in your GitHub repository. It covers common blockers such as missing access, protected branches, failing checks, and repositories that do not appear.

Before you start

• You can sign in to your Moxie Docs workspace.
• Your GitHub account is linked to the workspace with access to the target repository.
• You have write access on GitHub to open pull requests in the repository you want to update.
• You know which repository and branch Moxie Docs should propose changes to.

Repository does not appear in Moxie

You try to create a PR from Moxie Docs but the expected repository is missing in selection or search.

1. Confirm you are signed in to the correct Moxie Docs workspace that is connected to the right GitHub account.
2. Verify your GitHub account has access to the repository. Ask a repository owner to add you or your team if needed.
3. Refresh the repository list in Moxie Docs by reopening the PR creation flow, then search again by the exact repository name.
4. Check that the repository still exists and has not been archived or moved in GitHub.

• If you recently gained access on GitHub, wait a few minutes and try again so Moxie Docs can see the change.

You do not have permission to open a PR

You see an error about insufficient permissions when Moxie Docs tries to open or update a pull request.

1. Ask a repository admin to grant your GitHub user write access on the repository.
2. Request approval for any organization-level policy that limits third‑party app actions if your company uses them.
3. Retry the PR creation in Moxie Docs after access is granted.

• If access is intentionally restricted, share the proposed changes with a teammate who has permission and ask them to create the PR.

Branch is protected and PR cannot target it

Your default branch is protected on GitHub, and Moxie Docs cannot push changes directly or select it as an editable target.

1. Create a new feature branch name during PR creation in Moxie Docs if prompted, rather than targeting the protected branch directly.
2. Ensure you have permission to push branches to the repository. Ask a repository admin if branch creation is restricted.
3. Open the pull request from the feature branch into the protected branch, then follow your repository’s required review process in GitHub.

• Protected branch rules still apply after the PR is opened. Reviews and checks must pass before merging.

Required checks are failing on the PR

The pull request is created, but status checks (like CI, tests, or required reviews) fail and the PR cannot be merged.

1. Open the pull request in GitHub and review the “Checks” and “Conversation” tabs for failure details.
2. Resolve the reported issues in the repository (for example, update documentation content, fix link validations, or address formatting rules) using your normal contribution process.
3. Re-run the checks from GitHub if available, or push a small update from Moxie Docs by creating an updated PR commit.

• If your repository requires specific approvals, request reviews from the correct code owners or reviewers in GitHub.

PR was created but you cannot find it

Moxie Docs reported a successful PR, but you do not see it in GitHub or in your workspace.

1. Search for open and closed pull requests in the target repository by your username and today’s date.
2. Check if the PR was opened against a fork or a different branch than expected. Review the base and compare branches on the PR list.
3. Retry creating the PR from Moxie Docs, making sure you select the correct repository and base branch.

• Ask a teammate with repository admin access to confirm PR visibility if organization policies limit your view.

Updates to an existing PR are not appearing

You add new changes from Moxie Docs, but the existing PR does not update or shows outdated content.

1. Confirm you selected the same repository and branch as the open PR’s source branch when sending updates.
2. Wait a few minutes for GitHub to show the new commit on the PR, then refresh the PR page in GitHub.
3. Create a new PR if the original branch is locked or cannot accept new commits due to repository rules.

• If required checks are stuck in a pending state, re-open the PR page in GitHub and re-run checks if that control is available to you.

Organization policies block third‑party changes

Your company’s GitHub organization restricts actions by connected apps, which can prevent Moxie Docs from creating PRs.

1. Ask an organization owner to review app access policies and confirm that changes from your workspace are allowed for the target repository.
2. Validate that your GitHub user and the repository are included in any required allowlists.
3. Retry the PR creation in Moxie Docs after the policy is updated.

• If policies cannot be changed, coordinate with a repository maintainer to create the PR based on the proposed changes.

Still need help

• Recheck your repository access, the target branch, and any required checks in GitHub.
• If issues continue, contact your workspace admin to review permissions and connected accounts.
• Share the exact repository name, branch, and the time you attempted the PR to speed up troubleshooting.