Skip to main content
One of the most common blockers when someone new joins a docs team is not having the right access. They can see the repository but can’t push changes, or they can make edits but can’t adjust how the site is configured. Understanding the permission model upfront saves a lot of friction. There are two separate permission systems to understand: GitHub, which controls access to the repository itself, and Mintlify, which controls access to your site’s configuration.

​
GitHub repository permissions

GitHub uses a set of access levels to control what people can do in a repository. Read access lets someone view the repository contents and open issues. This is the default for public repositories and the minimum for anyone added to a private one. Read access alone isn’t enough to contribute documentation. You can see the files but can’t push changes. Write access is what most documentation contributors need. It allows you to create branches, push changes, and open pull requests. If someone on your team is trying to contribute but keeps getting permission errors, write access is almost always what they’re missing. Admin access gives full control over the repository, including settings, branch protection rules, and managing other users’ access. Typically only the repository owner and a small number of leads need this. If your repository is in a GitHub organization, access is usually managed at the team level. Your GitHub org admin adds people to a team, and that team is granted access to the relevant repositories. If you need access to a repository you can’t currently push to, ask your org admin or repo admin to add you with write permissions.

​
Mintlify dashboard permissions

The Mintlify dashboard has its own permission model that’s separate from GitHub. Anyone can be invited to collaborate in the Mintlify dashboard, but not all roles can change everything. The setting that comes up most often: Git settings (which branch Mintlify deploys from, repository connection details, and related configuration) can only be changed by a Mintlify admin. If you need to update how Mintlify is connected to your repository, you’ll need an admin in your Mintlify organization to make that change. For day-to-day documentation work (writing pages, updating navigation, previewing changes) standard access is sufficient.

​
The Mintlify GitHub app

When the Mintlify GitHub app is installed on your repository, it acts under its own set of permissions granted during installation. It can read your repository contents, post comments on pull requests with preview links, and report check results. If the app loses access (for example, because a GitHub org admin revokes it or the repository is transferred) previews and automatic deployments will stop working until access is restored. If your previews suddenly stop appearing on pull requests, the GitHub app’s permissions are usually the first thing to check. Next up: Workflow overview — the complete loop from making a change to seeing it live, using both the web editor and the CLI.