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.
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
Section titled “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:
One-click clone (recommended)
The clone option automatically creates a copy of your documentation in your GitHub account.
- Select GitHub as your provider.
- Click Clone.
- Authorize with GitHub when prompted.
- Select the GitHub organization where you want to create the repository.
- Confirm the clone. Mintlify copies your documentation files into a new repository.
- Optionally install the Mintlify GitHub App for automatic deployments.
Manual setup
If you prefer to set up your repository manually:
- Download your documentation as a zip file so that you have a backup of your files.
- Select GitHub as your provider.
- Click Continue setup.
- Authorize with GitHub when prompted.
- Select your organization, repository, and branch.
- Optionally specify a subdirectory if your docs are not at the repository root.
- Save your settings.
After completing either path, install the GitHub App by following the steps in Install the GitHub App.
Install the GitHub App
Section titled “Install the GitHub App”Install the Mintlify GitHub App on the Git settings page of your dashboard. When GitHub asks which repositories to grant access to, choose Only select repositories and select your documentation repository.
Permissions
Section titled “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
Manage repository access
Section titled “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
Section titled “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
Section titled “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
Section titled “Troubleshooting”Deployment not triggering automatically
Section titled “Deployment not triggering automatically”If pushes to your repository don't trigger deployments, check the following possible problems.
Verify GitHub App installation
Check that the correct repository has the app installed.
- Navigate to the Git settings page in your dashboard.
- Check that your repository is on the active app installations list.
Check deployment branch
Ensure that you're pushing to the correct branch.
- Go to Git Settings.
- Verify the branch in your dashboard matches the branch that you're pushing to.
GitHub App connection issues
Section titled “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.