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. If your team uses GitLab or Bitbucket, see GitLab or Bitbucket for the equivalent setup. The rest of this course still applies. By the end of this lesson, your site will be live and Mintlify will redeploy it whenever a change reaches your deployment branch.

​
Start with a repository

Go to mintlify.com/start and follow the onboarding flow. You can connect your GitHub account and choose a repository, or skip that step to get started faster. If you skip it, Mintlify creates a private repository for you in its own GitHub organization. You can use the web editor right away, but you can’t clone that repository or work locally until you copy it to your own account. Use the one-click clone in Git Settings when you’re ready. 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. Choose Only select repositories and select your 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 follows the principle of least privilege: if something goes wrong, the app can’t touch anything else.

​
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. To confirm the connection works end to end, make a small change, like fixing a typo, and merge it to your deployment branch. A new deployment should appear in the dashboard within a minute or two. If it doesn’t, the next lesson covers what to check. 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.