Skip to main content
When you deploy documentation on Mintlify from a GitHub repository, access and permissions are split between GitHub and Mintlify. GitHub controls repository access. Mintlify controls what someone can do in the dashboard and editor.

​
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 and dashboard information but can’t edit or publish.
  • Editor: Create and edit pages, update navigation, publish changes, and trigger deployments.
  • Admin: Everything an editor can do and manage restricted settings like roles, billing, domains, and the Git source.
Most people on your team require an editor role. Reserve admin roles for people responsible for the repository itself. Role-based access controls depend on your Mintlify plan. See Roles in the Mintlify documentation for more information.

​
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
Next up: Set up your local environment — Clone the repository and run a local documentation preview.