Skip to main content
Mintlify needs two things from GitHub: a repository containing your documentation and permission to read and deploy it. The Mintlify GitHub app provides that connection. By the end of this lesson, a push to your configured deployment branch will trigger a Mintlify deployment.

​
Start with a repository

Go to mintlify.com/start and follow the onboarding flow. You can connect a repository you already own or use the repository option offered during onboarding. If you connect an existing repository, make sure it contains—or will contain—your Mintlify project. At minimum, the project needs a docs.json configuration file and a page included in its navigation. The GitHub account completing this setup must be allowed to install or request the Mintlify GitHub app for the repository. In an organization, an owner may need to approve the installation.

​
Choose the repository Mintlify can access

During installation, GitHub asks which repositories the Mintlify app can access. Grant access to the documentation repository. You can update that selection later in the GitHub app settings if the repository changes. Mintlify uses the connection to:
  • Read the documentation source
  • Deploy changes pushed to the configured deployment branch
  • Create preview deployments for pull requests
  • Create branches and pull requests from the web editor
  • Report configured checks in GitHub
Granting access only to the repositories Mintlify needs keeps the integration’s scope easy to understand.

​
Confirm the source and deployment

In your Mintlify dashboard, open Git Settings and confirm the organization, repository, and deployment branch. The deployment branch is often main, but use whatever branch your team has configured. After the first successful build, open the site URL from the dashboard. If the repository is connected but changes don’t deploy, check these three things first:
  1. The commit reached the configured deployment branch.
  2. The GitHub app still has access to the repository.
  3. The latest deployment in the dashboard completed successfully.
You can find the full installation and permission details in the GitHub deployment guide. Next up: Access and permissions — identify whether a GitHub or Mintlify role is blocking the work.