Mintlify integrates with the GitHub API, enabling synchronization between your docs and your GitHub repository. This integration is made possible through the utilization of GitHub Apps.

​
Installation

To begin, you need to install the Mintlify GitHub App into the GitHub account where your docs repo resides. Installing a GitHub App requires either organization ownership or admin permissions in a repository. If you lack the necessary permissions, the repository owner will need to approve the request.

You can access the installation page by logging into the Mintlify dashboard.

For GitHub Apps, you can choose to give permissions to a single repository. We highly recommend this approach as we only need access to the repository where your docs are hosted.

​
Permissions

During the installation of our GitHub App, you will be prompted to grant certain permissions:

  • Read and write access to checks, contents, deployments, pull requests, and workflows

These permissions are leveraged to provide a seamless experience when managing your docs.

When you make a commit to your configured docs deployment branch, we fetch the contents of the changed files to update your docs. This requires read access to your repository’s contents.

When Pull Requests are created, we create a check and preview deployment. This requires write access to checks and deployments.

Inside the Mintlify web editor, Mintlify works on your behalf to create branches and Pull Requests, which requires write access to pull requests and workflows.

If you are concerned about the write permissions, the GitHub App will only have access to the repositories you explicitly grant access to. Additionally, if you have branch protections enabled, the App cannot push directly to your branches—it must abide by your branch protection rules.

​
Repository Installations

When installing our GitHub App, you will be prompted to select either all repositories or a specific subset. You can modify this selection at any time by visiting the GitHub App settings.

Was this page helpful?