mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
ed545fa56a
* Update deploy/github.mdx * Update deploy/github.mdx --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
98 lines
4.6 KiB
Plaintext
98 lines
4.6 KiB
Plaintext
---
|
|
title: "GitHub"
|
|
description: "Connect to a GitHub repository for automated deployments, pull request previews, and continuous synchronization."
|
|
keywords: ["GitHub App", "repository connection", "automated deployments"]
|
|
---
|
|
|
|
Mintlify uses a GitHub App to automatically sync your documentation with your GitHub repository.
|
|
|
|
## Installing the GitHub App
|
|
|
|
<Note>
|
|
You must have organization ownership or administrator permissions in a repository to install the app. If you lack the necessary permissions, the repository owner must approve the installation request.
|
|
</Note>
|
|
|
|
Install the Mintlify GitHub App through your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app).
|
|
|
|
<Tip>
|
|
We recommend granting access only to the repository where your docs are hosted.
|
|
</Tip>
|
|
|
|
<Frame>
|
|
<img className="h-80" alt="Mintlify GitHub App installation page with the 'Only select repositories' option selected." src="/images/github/select-repos.png" />
|
|
</Frame>
|
|
|
|
## Permissions
|
|
|
|
When you install the GitHub app, you will be prompted to grant the following permissions:
|
|
|
|
Read permissions:
|
|
* `metadata`: Basic repository information
|
|
|
|
Read and write permissions:
|
|
* `checks`: Create status checks on pull requests
|
|
* `code`: Read file changes when you commit to your docs branch
|
|
* `deployments`: Generate preview deployments for pull requests
|
|
* `pull requests`: Create branches and pull requests from the web editor
|
|
|
|
<Info>
|
|
The app only accesses repositories that you explicitly grant it access to. If you have branch protection rules enabled, the app can't push directly to protected branches.
|
|
</Info>
|
|
|
|
## Managing repository access
|
|
|
|
When installing our GitHub App, you can grant access to all of your repositories or specific ones. We recommend only granting access to the repositories where your documentation is located. You can modify this selection anytime in your [GitHub app settings](https://github.com/apps/mintlify/installations/new).
|
|
|
|
## Configuring docs source
|
|
|
|
Change the organization, repository, or branch that your documentation is built from in the [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) section of your dashboard.
|
|
|
|
## 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.
|
|
|
|
Follow [GitHub's documentation](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization) to configure your IP allowlist.
|
|
|
|
## Troubleshooting
|
|
|
|
### GitHub app connection issues
|
|
|
|
If you encounter problems with the GitHub app, resetting the connection can solve most problems.
|
|
|
|
<Steps>
|
|
<Step title="Uninstall the Mintlify app through GitHub.">
|
|
1. In GitHub, go to [installations](https://github.com/settings/installations) and select **Configure** next to the Mintlify app. Scroll down and select **Uninstall**.
|
|
2. Go to [Authorized GitHub Apps](https://github.com/settings/apps/authorizations) and select **Revoke** next to the Mintlify app.
|
|
</Step>
|
|
<Step title="Reinstall the Mintlify app.">
|
|
1. In your Mintlify dashboard, go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) and install the GitHub app.
|
|
2. Authorize your account in the [My Profile](https://dashboard.mintlify.com/settings/account) section of your dashboard.
|
|
</Step>
|
|
</Steps>
|
|
|
|
### Feedback add-ons are unavailable
|
|
|
|
If you cannot enable the edit suggestions or raise issues options in your dashboard and your repository is public, revalidate your Git settings.
|
|
|
|
<Steps>
|
|
<Step title="Navigate to Git Settings">
|
|
Go to [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) in your dashboard.
|
|
</Step>
|
|
<Step title="Revalidate your settings">
|
|
Click the green check mark in the corner of the Git settings box to revalidate your repository settings. This will force update your repository settings to reflect whether your repository is public or private.
|
|
|
|
<Frame>
|
|
<img
|
|
src="/images/github/revalidate-settings-light.png"
|
|
alt="The Git Settings page in the Mintlify dashboard. An orange arrow points to the green check mark that revalidates the repository settings."
|
|
className="block dark:hidden"
|
|
/>
|
|
<img
|
|
src="/images/github/revalidate-settings-dark.png"
|
|
alt="The Git Settings page in the Mintlify dashboard. An orange arrow points to the green check mark that revalidates the repository settings."
|
|
className="hidden dark:block"
|
|
/>
|
|
</Frame>
|
|
</Step>
|
|
</Steps>
|