Skip to content

Update from support feedback: document GitHub connection reset and editor recovery #6433

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify-development wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update from support feedback: document GitHub connection reset and editor recovery #6433

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 31 additions & 6 deletions deploy/github.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,12 @@

Change the organization, repository, or branch that your documentation builds from in the [Git Settings](https://app.mintlify.com/settings/deployment/git-settings) section of your dashboard.

<Warning>
Connecting a new Git repository replaces your Mintlify-hosted content with the contents of the repository that you select. If you connect an empty or unrelated repository, your previous documentation files are no longer accessible from the web editor.

Before you change your Git settings, download a zip of your documentation from the setup wizard so that you have a backup. If you only want to explore the Git Settings page, do not select a repository or save any configuration.
</Warning>

## GitHub Enterprise with IP allowlists

If your GitHub Enterprise Cloud organization has an IP allowlist enabled, you need to add Mintlify's egress IP address (`54.242.90.151`) to your allowlist for the GitHub App to function properly.
Expand Down Expand Up @@ -127,19 +133,38 @@

### GitHub app connection issues

If you encounter problems with the GitHub app, resetting the connection can solve most problems.
If you encounter problems with the GitHub app, resetting the connection resolves most problems. Common symptoms include the web editor showing **GitHub App Installation Required**, the dashboard being unable to list your repositories, or GitHub OAuth only requesting the `public_repo` scope so that your private repositories are not selectable.

Complete all four steps in order. Skipping the uninstall or revoke step leaves stale credentials that cause the reinstall to fail silently.

<Steps>
<Step title="Uninstall the Mintlify app through GitHub.">
1. In GitHub, go to [installations](https://github.com/settings/installations) and click **Configure** next to the Mintlify app. Scroll down and click **Uninstall**.
2. Go to [Authorized GitHub Apps](https://github.com/settings/apps/authorizations) and click **Revoke** next to the Mintlify app.
<Step title="Uninstall the Mintlify app from GitHub.">
Go to [GitHub App installations](https://github.com/settings/installations), find **Mintlify**, click **Configure**, scroll to the bottom, and click **Uninstall**.
</Step>
<Step title="Revoke the Mintlify authorization.">
Go to [Authorized GitHub Apps](https://github.com/settings/applications), find **Mintlify** under **Authorized GitHub Apps**, and click **Revoke**.
</Step>
<Step title="Reinstall the Mintlify app.">
1. In your Mintlify dashboard, go to [Git Settings](https://app.mintlify.com/settings/deployment/git-settings) and install the GitHub app.
2. Authorize your account in the [My Profile](https://app.mintlify.com/settings/account) section of your dashboard.
In your Mintlify dashboard, go to [Git Settings](https://app.mintlify.com/settings/deployment/git-settings), install the GitHub app, select your GitHub organization or account, and grant access to your docs repository.
</Step>
<Step title="Re-authorize your GitHub account.">
Go to [account settings](https://app.mintlify.com/settings/account) and click **Authorize GitHub account** to complete the authorization. This step re-issues the OAuth token with the correct scopes for both public and private repositories.
</Step>
</Steps>

### Editor shows "GitHub App Installation Required"

Check warning on line 155 in deploy/github.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/github.mdx#L155 

'Editor shows "GitHub App Installation Required"' should use sentence-style capitalization.

If the web editor shows **GitHub App Installation Required** after you opened Git Settings or connected a repository, the dashboard is expecting a GitHub-backed source that is not fully connected.

- If you opened Git Settings without selecting a repository or saving, your Mintlify-hosted content is still intact. Complete the [GitHub app connection reset](#github-app-connection-issues) to restore access to the editor.
- If you connected a repository, the editor now points at that repository. Reset the connection with the steps above, then reconnect to the correct repository from [Git Settings](https://app.mintlify.com/settings/deployment/git-settings).

Check warning on line 160 in deploy/github.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/github.mdx#L160 

Use 'preceding' instead of 'above'.

### Recover the previous Mintlify-hosted content

If you connected the wrong repository (for example, an empty repository) and your original Mintlify-hosted documentation is no longer visible in the editor, the previous content is not automatically restored when you disconnect. Reach out to [support](mailto:support@mintlify.com) with your deployment name and organization ID. Support can share a zip of your previous Mintlify-hosted repository contents so that you can re-upload them or push them to the correct repository.

To avoid this situation in the future, download a backup zip from the Git Settings setup wizard before you connect any repository.

### Feedback add-ons are unavailable

The edit suggestions and raise issues feedback features are only available for public GitHub repositories. If these options are unavailable in your dashboard, check your repository visibility.
Expand Down
Loading