GitHub
Connect your GitHub repository to Mintlify for automated deployments, pull request preview builds, and continuous documentation synchronization.
Mintlify uses a GitHub App to automatically sync your documentation with your GitHub repository.
Do you need the GitHub App?
- Mintlify-hosted repository in the
mintlify-communityorganization: No. The GitHub App is already configured. - Your own repository: Yes. Install the GitHub App to enable automatic deployments when you push changes.
See your repository in the Git Settings page of your dashboard.
If your repository is in a private repository owned by the Mintlify organization, the GitHub App is automatically configured and managed by Mintlify. You can use the web editor to make changes to your documentation. If you want to work on your documentation locally, clone the repository to your own organization and update your Git settings to use your own repository.
Clone to your own repository
If you skipped connecting your own Git repository during onboarding, your documentation lives in a private repository owned by the Mintlify organization. To move it to your own account or organization, go to Git Settings in your dashboard. A setup wizard guides you through the process with two options:
After completing either path, install the GitHub app by following the steps in Install the GitHub app.
Install the GitHub app
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.
Install the Mintlify GitHub App on the Git settings page of your dashboard.
Permissions
When you install the GitHub App, grant the following permissions.
Read permissions:
metadata: Basic repository information
Read and write permissions:
checks: Create status checks on pull requestscode: Read file changes when you commit to your docs branchdeployments: Generate preview deployments for pull requestspull requests: Create branches and pull requests from the web editor
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.
Manage repository access
When installing the GitHub App, you can grant access to all of your repositories or specific ones. Grant access only to your documentation repository and any repositories that you want to provide as context for the agent or workflows. You can modify this selection anytime in your GitHub App settings.
Configure docs source
Change the organization, repository, or branch that your documentation builds from in the 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 to configure your IP allowlist.
Troubleshooting
Deployment not triggering automatically
If pushes to your repository don’t trigger deployments, check the following possible problems.
GitHub app connection issues
If you encounter problems with the GitHub app, resetting the connection can solve most problems.
Uninstall the Mintlify app through GitHub.
- In GitHub, go to installations and click Configure next to the Mintlify app. Scroll down and click Uninstall.
- Go to Authorized GitHub Apps and click Revoke next to the Mintlify app.
Reinstall the Mintlify app.
- In your Mintlify dashboard, go to Git Settings and install the GitHub app.
- Authorize your account in the My Profile section of your dashboard.