diff --git a/dashboard/roles.mdx b/dashboard/roles.mdx
index e1620f6bd..964f673ed 100644
--- a/dashboard/roles.mdx
+++ b/dashboard/roles.mdx
@@ -66,7 +66,7 @@ Organizations with expanded roles have six roles: owner, admin, publisher, edito
You can only invite members or assign roles up to your own role.
- **Owner**: Everything an admin can do, plus deleting the project, deleting the organization, and transferring ownership. Every organization has one owner, starting with the person who creates it.
-- **Admin**: Full control over content, members, roles, and settings, including billing and the custom domain. Admins can publish without review.
+- **Admin**: Full control over content, members, roles, and settings, including billing and the custom domain. Admins can publish without review, unless your deployment branch has branch protection.
- **Publisher**: Everything an editor can do, plus publishing changes and approving [review requests](/editor/review#require-review-before-publishing).
- **Editor**: Create and edit content, comment, request reviews, and manage site and workspace settings, integrations, API keys, and the assistant. Editors can't publish or approve reviews.
- **Commenter**: Everything a viewer can do, plus commenting on pages.
diff --git a/editor/publish.mdx b/editor/publish.mdx
index ff46eac52..f0ca95f8d 100644
--- a/editor/publish.mdx
+++ b/editor/publish.mdx
@@ -36,6 +36,7 @@ Click **Publish** in the toolbar to see your pending changes. Click any changed
| Deployment branch | None | **Publish** directly to your live site |
| Deployment branch | Pull requests required | **Create branch** to move your work to a new branch |
| Deployment branch with [Require review before publishing](/editor/review#require-review-before-publishing) on | None | **Request review**. Admins can also **Publish** directly |
+| Deployment branch with [Require review before publishing](/editor/review#review-with-a-protected-deployment-branch) on | Protected, on GitHub.com | **Create branch**, then **Request review** on the new branch |
| Feature branch | None | **Request review**, then **Merge and publish** |
| Feature branch with [Require review before publishing](/editor/review#review-changes-on-a-branch) on | None | **Request review**, then **Publish approved changes** once reviewers approve every page. Admins can also **Publish** directly |
| Feature branch in a repository that Mintlify hosts, with no required approvals | None | **Publish** to merge the branch into your deployment branch |
diff --git a/editor/review.mdx b/editor/review.mdx
index c4c397f33..4b990861e 100644
--- a/editor/review.mdx
+++ b/editor/review.mdx
@@ -44,7 +44,7 @@ To point a teammate at a specific page on a branch, click
-If an admin turns on [Require review before publishing](/editor/settings#require-review-before-publishing), changes on your deployment branch and on branches you create in the editor need a teammate's approval before an admin or publisher can publish them. Admins can publish their own changes without review.
+If an admin turns on [Require review before publishing](/editor/settings#require-review-before-publishing), changes on your deployment branch and on branches you create in the editor need a teammate's approval before an admin or publisher can publish them. Admins can publish their own changes without review, unless your deployment branch has branch protection.
On a branch, reviewers approve each page in the editor, the same way as on your deployment branch. See [Review changes on a branch](#review-changes-on-a-branch).
@@ -72,7 +72,7 @@ Changes that don't belong to a page, such as navigation, site settings, and dele
While a page is in an open review request, the sidebar shows **In review** next to it. After a reviewer approves the page, the sidebar shows **Approved**.
-Admins can publish without review, but they can also request a review from the **Publish** menu.
+Admins can publish without review on an unprotected deployment branch, but they can also request a review from the **Publish** menu.
### Review and approve changes
@@ -128,10 +128,26 @@ A review on a branch covers the whole branch. Every page of the branch shows one
- If you edit the branch after approval, or someone pushes a change to it in Git, the banner shows **You edited this branch after it was approved** or **This branch changed in git after it was approved**. Click **Request review again** to ask the reviewers to review it again.
- Pages you delete on the branch are part of the review too. They appear as **Removed**, and reviewers approve them like any other page. A removed page's link in the review banner opens the page on your deployment branch in a new tab.
- If the branch no longer changes a requested page, the page leaves the review request.
+- Reviews that teammates leave on the branch's pull request in GitHub appear in the review request and in the [inbox](/dashboard/inbox) for reference. They don't count as approvals in the editor.
- If someone else published a change to the same part of a page, the publish menu shows **Can't publish these changes** and disables **Publish**. Admins can click **View request** to resolve the conflict. Everyone else should ask an admin for help.
On a [sub-branch](/editor/publish#sub-branches), the publish menu still shows **Publish to** your deployment branch and **Merge into** the parent branch.
+### Review with a protected deployment branch
+
+If your deployment branch has branch protection, you can still require review before publishing when your repository is on GitHub.com. GitHub Enterprise Server repositories with a protected deployment branch can't use this setting.
+
+1. On your deployment branch, click **Create branch** to move your changes to a new branch.
+1. Click **Request review** and choose reviewers. Mintlify opens the branch's pull request, or marks its draft pull request ready for review, then sends the review request.
+1. Reviewers open the request from their inbox and click **Approve** in the editor.
+1. After approval, an admin or publisher clicks **Publish approved changes**.
+
+If a reviewer has [connected their GitHub account](/dashboard/profile#connect-github), approving in the editor also approves the pull request in GitHub for the commit they reviewed. If your branch protection requires a GitHub approval and the reviewer hasn't connected GitHub, the editor asks them to connect their account first.
+
+Publishing merges only the version of the branch that reviewers approved. If you edit the branch after approval, request review again. GitHub's merge checks, such as required status checks, still apply.
+
+With a protected deployment branch, admins can't publish without review. Approvals made directly in GitHub don't count as approvals in the editor.
+
## Review and merge pull requests
When your branch has a pull request, the publish menu shows its changed files and review status, like **Pull request created**, **Review required**, **Changes requested**, or **Approved**. If Mintlify hosts your repository, a draft shows **Draft in progress**. If your repository is in your own Git provider, such as GitHub, GitLab, or Bitbucket, click **View request** to open the pull request there.
diff --git a/editor/settings.mdx b/editor/settings.mdx
index 0aaeb1cf5..d37636c3b 100644
--- a/editor/settings.mdx
+++ b/editor/settings.mdx
@@ -52,7 +52,7 @@ When you require review before publishing, only admins can publish changes direc
- Only admins can turn this setting on or off.
- Requiring reviews before publishing turns off [auto publish](#auto-publish).
-- You can't turn on this setting while your deployment branch has branch protection. To use it, turn off branch protection on your deployment branch in GitHub. To keep branch protection, review changes through [pull requests](/editor/review#review-and-merge-pull-requests) instead.
+- If your deployment branch has branch protection, your repository must be on GitHub.com. Reviews then happen on branches, and admins can't publish without review. See [Review with a protected deployment branch](/editor/review#review-with-a-protected-deployment-branch).
- Reviews work on your deployment branch and on branches you create in the editor. On a branch, an admin or publisher can publish once reviewers approve every changed page. See [Review changes on a branch](/editor/review#review-changes-on-a-branch).
## Create draft pull requests by default