Skip to main content
When you deploy documentation on Mintlify from a GitHub repository, access is split between two systems. GitHub controls who can change the repository. Mintlify controls what someone can do in the dashboard and editor. When someone gets stuck, the first question is which system is blocking them.

​
GitHub controls the repository

For most documentation teams, you only need to know these GitHub repository permissions:
  • Read: View and clone a repository. A contributor with read access can also propose changes through a fork if the organization allows that workflow.
  • Write: Push branches to the repository, open pull requests from those branches, review changes, and merge when branch rules allow it. This is the usual role for regular internal contributors.
  • Admin: Manage repository access, settings, and branch protection. Reserve it for people responsible for the repository itself.
GitHub also offers Triage and Maintain permissions. They can be useful for teams with more specialized responsibilities, but they aren’t relevant to the everyday branch workflow. Organization repositories often grant access through teams. If a contributor can clone the repository but can’t push a branch, ask a repository or organization administrator whether they should receive write access or use a fork-based workflow.

​
Mintlify controls the dashboard and editor

Mintlify uses viewer, editor, and admin roles.
  • Viewer: View content, the dashboard, and analytics. In the editor, viewers can leave comments and suggest changes, but can’t edit or publish.
  • Editor: Create and edit pages, update navigation, publish changes, and trigger deployments.
  • Admin: Everything an editor can do, plus manage roles, billing, SSO, the custom domain, and the Git source.
Most people on your team need an editor role. Limit admin roles to the people who handle account-level settings. If your organization doesn’t use role-based access control, every member has full access and new members join as editors. See Roles for the full list of permissions.

​
Repository access can bypass dashboard roles

The two systems don’t check each other. Anyone with write access to the repository can push to the deployment branch, and that push deploys, whatever their Mintlify role. A viewer in Mintlify with write access in GitHub can still publish. If publishing should require review, enforce it in GitHub with branch protection on the deployment branch. Mintlify roles only control what people can do in the dashboard and editor.

​
The GitHub App has separate access

The Mintlify GitHub App acts with the permissions approved during installation. Someone on your team can have the correct GitHub and Mintlify roles while deployments still fail because the app no longer has access to the repository. Check the app connection when any of the following occur:
  • New commits on the deployment branch don’t trigger builds
  • Pull requests stop receiving preview deployments
  • The repository was renamed, transferred, or replaced
  • An organization administrator recently changed GitHub App access
If deployments stop, first confirm the commit actually reached the deployment branch and check the latest deployment’s status in the dashboard. If both look fine, check the app. Open your GitHub organization’s Settings > GitHub Apps, select the Mintlify app, and confirm the documentation repository is in its list. Then confirm the repository and deployment branch in Mintlify’s Git Settings. Next up: Set up your local environment—clone the repository and run a local documentation preview.