Document ABAC permission policies and team-scoped membership policies (v11.7)

[Combs7th]

Summary

Cohesive v11.7 ABAC docs update.

• ABAC overview: "ABAC can be used with" framing for system-wide access, permission, team-scoped membership, and channel-specific access policies; clarifies who manages each.
• System-wide policies: unique-name validation note for parent policies and new Permission policies section covering attribute-based file upload / file download restrictions.
• Channel access rules: new Manage team-scoped membership policies in Team Settings section covering the Team Admin workflow via the Membership Policies tab, manage_team_access_rules permission, Team Settings sync status footer (Last sync time, Sync now), team-scope sync limits, and auto-run sync on team admin policy creation.
• Share files in messages: short Restricted file attachments end-user note.
• Permissions reference: manage_team_access_rules added to the permission table and to the team_admin built-in role.

Closes #`8950

Reviewer notes

• Tab label: Used Membership Policies for the Team Settings tab throughout, per cleanup-pass guidance. Reconcile against a v11.7.0 test instance before merge if the final shipped UI label differs.
• SCREENSHOT NEEDED: Capture Team Settings → Membership Policies area from a v11.7.0 test instance, including the sync status footer if visible.
• Build / link check: Local Sphinx build could not be run in the Claude sandbox (pipenv / sphinx-build not installed). Please run make html and make linkcheck locally before merge to verify the new :ref: anchors resolve:
  • administration-guide/manage/admin/abac-system-wide-policies:permission policies
  • administration-guide/manage/admin/abac-channel-access-rules:manage team-scoped membership policies in team settings
  • end-user-guide/collaborate/share-files-in-messages:restricted file attachments

Test plan

• make html completes without new warnings.
• make linkcheck or Sphinx nitpicky mode resolves all new :ref: anchors.
• ABAC overview renders the four policy-type bullets and the System / Team / Channel admin breakdown.
• System-wide policies page renders the Permission policies section and the unique-name note inside step 2.
• Channel-specific access rules page renders the new Manage team-scoped membership policies in Team Settings section with Prerequisites, Team Admin workflow, Team Settings sync status footer, and Auto-run sync subsections.
• Share-files-in-messages page renders the Restricted file attachments section with a working cross-link.
• Permissions reference renders the new manage_team_access_rules row and the updated team_admin role list.
• Reconcile Membership Policies tab label against a v11.7.0 test instance.

Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds comprehensive documentation for Mattermost v11.7+ ABAC enhancements, including team-scoped membership policies managed by Team Admins, system-admin permission policies for restricting file uploads/downloads, updated permission infrastructure, and end-user guidance on restricted file attachments.

Changes

ABAC v11.7+ Features

Layer / File(s)	Summary
ABAC Conceptual Overview source/administration-guide/manage/admin/attribute-based-access-control.rst	ABAC overview is updated to replace the two-level control description with a clearer breakdown of four policy types: system-wide access policies, permission policies, team-scoped membership policies, and channel-specific access rules.
Permission Infrastructure source/administration-guide/onboard/advanced-permissions-backend-infrastructure.rst	New manage_team_access_rules permission (team scope) is added to the Mattermost permissions table and included in the team_admin built-in role default permissions.
System-Admin Access Control Policies source/administration-guide/manage/admin/abac-system-wide-policies.rst	Policy name step now documents uniqueness requirement for parent access control policy names with duplicate-blocking error message. Channel policy removal instructions clarified to describe disabling via Remove Policy and relinking to a different policy.
System-Admin Permission Policies source/administration-guide/manage/admin/abac-system-wide-policies.rst	New "Permission policies" section describes v11.7+ system-admin ABAC-based permission policies that restrict file upload and file download actions, including user-facing behavior when attribute rules block access and uniqueness constraint for parent permission policy names.
Team-Admin Team-Scoped Membership Policies source/administration-guide/manage/admin/attribute-based-access-control.rst, source/administration-guide/manage/admin/abac-channel-access-rules.rst	Introduces Team Admin capability to create/edit/delete team-scoped channel membership policies in Team Settings (v11.7+) for private channels, with prerequisites, step-by-step workflow, sync status footer with on-demand sync, scoping limits for team-wide sync triggers, and automatic sync execution when creating policies with auto-add enabled.
End-User Restricted File Attachments source/end-user-guide/collaborate/share-files-in-messages.rst	New "Restricted file attachments" section explains how ABAC policies restrict file uploads/downloads, what users observe when attachments are redacted or blocked, and directs users to contact administrators for access while pointing admins to permission policy details.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• 11.7: Document ABAC permission policies and team-scoped membership policy workflows #8950: Team-scoped membership policies, permission policies, unique parent-policy name validation, and sync UI documentation implement the same ABAC v11.7+ features described in this issue.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: documenting ABAC permission policies and team-scoped membership policies for Mattermost v11.7, which aligns with all file modifications.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, detailing each modified documentation file, the new sections added, permissions changes, and reviewer notes with specific testing requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/issue-8950-20260511-2015

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

source/administration-guide/manage/admin/abac-channel-access-rules.rst (1)

118-119: ⚡ Quick win

Promote the team-scope sync constraint to an important admonition

The scope boundary here affects operational expectations and should stand out more than body text.

Suggested minimal diff

-Team-scoped sync is limited to the team admin's team scope. Triggering **Sync now** from Team Settings does not affect channels or policies outside the current team.
+.. important::
+
+  Team-scoped sync is limited to the Team Admin's team scope. Triggering **Sync now** from Team Settings does not affect channels or policies outside the current team.

As per coding guidelines, "Use important admonition for prerequisites, constraints, or high-impact information that materially affects correctness, supportability, compliance, or success".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@source/administration-guide/manage/admin/abac-channel-access-rules.rst`
around lines 118 - 119, Wrap the sentence "Team-scoped sync is limited to the
team admin's team scope. Triggering **Sync now** from Team Settings does not
affect channels or policies outside the current team." in an important
admonition so the scope boundary stands out; replace the plain paragraph with an
reStructuredText admonition using the .. important:: directive and the same text
indented beneath it (preserve the bold **Sync now** text and punctuation) to
emphasize this high-impact constraint.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@source/administration-guide/manage/admin/attribute-based-access-control.rst`:
- Line 50: Replace the vague phrase "appropriate permission" with the explicit
permission key manage_team_access_rules in the sentence that describes
creating/editing/deleting team-scoped channel membership policies (the sentence
referencing :ref:`team-scoped channel membership policies
<administration-guide/manage/admin/abac-channel-access-rules:manage team-scoped
membership policies in team settings>`), so the sentence reads that admins can
perform those actions "when granted the manage_team_access_rules permission" to
match product/config naming conventions.

---

Nitpick comments:
In `@source/administration-guide/manage/admin/abac-channel-access-rules.rst`:
- Around line 118-119: Wrap the sentence "Team-scoped sync is limited to the
team admin's team scope. Triggering **Sync now** from Team Settings does not
affect channels or policies outside the current team." in an important
admonition so the scope boundary stands out; replace the plain paragraph with an
reStructuredText admonition using the .. important:: directive and the same text
indented beneath it (preserve the bold **Sync now** text and punctuation) to
emphasize this high-impact constraint.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9a30e925-e528-44b3-9184-5f0e5e117e87

📥 Commits

Reviewing files that changed from the base of the PR and between d63b6e0 and 6fe245e.

📒 Files selected for processing (5)

• source/administration-guide/manage/admin/abac-channel-access-rules.rst
• source/administration-guide/manage/admin/abac-system-wide-policies.rst
• source/administration-guide/manage/admin/attribute-based-access-control.rst
• source/administration-guide/onboard/advanced-permissions-backend-infrastructure.rst
• source/end-user-guide/collaborate/share-files-in-messages.rst

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 6fe245e

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA f32cab9

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 8d2a37d

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 9ee1b92

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 426da39

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 5bb8428

[Combs7th]

@claude - Please call out manage_team_access_rules directly as coderabbitai points out above.

[claude]

Claude finished @Combs7th's task in 30s —— View job

---

Updated per CodeRabbit feedback

• Read the file at line 50
• Replace "appropriate permission" with explicit manage_team_access_rules permission key
• Commit and push the change

Summary

Updated source/administration-guide/manage/admin/attribute-based-access-control.rst:50 — the Team Admins bullet now names the manage_team_access_rules permission explicitly instead of saying "the appropriate permission," so role-mapping validation is unambiguous.

Pushed as commit 260da2f.
| Branch: claude/issue-8950-20260511-2015

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 260da2f

[Combs7th]

Heya @isacikgoz and @pvev - Tagging y'all for the dev review on this one. Any crucial pieces that I'm missing here?

Main things I’d love confirmed:

• Is “Membership Policies” the correct final Team Settings tab label?
• Does the Team Admin workflow look accurate?
• Is the manage_team_access_rules permission described correctly?
• Does the sync behavior language look right?

Thanks so much!

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 260da2f

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 260da2f

[pvev]

hey, thanks @Combs7th , so mostly correct, a couple of things that should be updated:

1. Team-scoped policies are not limited to private channels. Both public and private channels can be assigned.

   What differs is the sync behavior:

   • Public channels = advisory sync (add only)
   • Private channels = enforced sync (can also remove users if rules now exclude them)

2. Auto-run sync is not gated behind auto-add. So, whenever there are rule/channel/active-state changes, not only when "auto-add" or sync behavior is enabled.

3. The end-user copy for restricted file attachments should reference the actual UI placeholder strings so users can recognize the state more easily:

   • Title: Files not available
   • Subtitle: Access to files is restricted based on attributes

[Combs7th]

Thanks Pablo! This is super helpful.

@claude - Please apply a targeted cleanup commit based on the above dev review feedback from pvev.

Do not rewrite the whole docs update. Only make the corrections below.

Updates needed:

1. Team-scoped policy channel assignment

• Update the docs to clarify that team-scoped membership policies are not limited to private channels.
• Both public and private channels can be assigned to team-scoped policies.

2. Sync behavior distinction

• Update the sync behavior docs to distinguish public vs private channel behavior:
  • Public channels: advisory sync / add-only behavior.
  • Private channels: enforced sync / can remove users if they no longer match the policy rules.
• Keep the language admin-facing and concise.
• Do not over-explain backend implementation.

3. Auto-run sync behavior

• Update the auto-run sync guidance.
• It should not say or imply that auto-run sync is gated behind auto-add.
• Correct behavior: sync runs automatically when there are rule, channel, or active-state changes.

4. End-user restricted file attachment copy

• Update the restricted file attachment note to reference the actual UI placeholder strings:
  • Title: “Files not available”
  • Subtitle: “Access to files is restricted based on attributes”
• Keep this section short so users can recognize the state without adding unnecessary detail.

5. Final cleanup

• Make sure there are no PR numbers, Jira IDs, internal reviewer notes, or [NOT PRESENT IN PR] markers in published docs content.
• Keep any unresolved review notes in the PR description only.
• Attempt the docs build/link check if available. If unavailable, note that in the PR description only.

After editing, provide:

• Files changed.
• Brief summary of each correction.
• Updated PR summary.
• Any remaining reviewer notes.

[claude]

Claude finished @Combs7th's task in 3m 5s —— View job

---

Cleanup pass based on @pvev's review — done

• Read affected files to ground edits in current text
• Fix test branch #1: Team-scoped policies apply to public and private channels
• Fix Update Troubleshooting.md #2: Distinguish public (advisory, add-only) vs private (enforced, can remove) sync behavior
• Fix Pushing css changes for mattermost docs #3: Auto-run sync triggers on rule/channel/active-state changes — not gated behind auto-add
• Fix Fixing css issue #4: End-user copy references actual UI strings (Files not available / Access to files is restricted based on attributes)
• Fix Changing css file name #5: Scan for PR numbers, Jira IDs, internal reviewer notes, [NOT PRESENT IN PR] markers — none found in docs content
• Commit & push

Pushed as commit 5c402bd.

---

Files changed (3)

File	Change
source/administration-guide/manage/admin/abac-channel-access-rules.rst	Drop private-only restriction in intro + Prerequisites bullet; add Sync behavior by channel type subsection; rename and rewrite auto-run sync subsection.
source/administration-guide/manage/admin/attribute-based-access-control.rst	Drop "for private channels" from the team-scoped bullet in the ABAC overview policy-type list and the "Team Admins can:" section.
source/end-user-guide/collaborate/share-files-in-messages.rst	Reference the actual UI placeholder strings Files not available and Access to files is restricted based on attributes.

Per-correction summary

1. Channel assignment scope (test branch #1) — Three call sites updated. The intro paragraph, the Prerequisites bullet, and both top-level overview references now describe team-scoped policies as applicable to channels in the team (not private-only).
2. Sync behavior distinction (Update Troubleshooting.md #2) — New Sync behavior by channel type subsection added between the sync footer and auto-run sync sections. Two-bullet admin-facing summary: public = advisory/add-only; private = enforced (adds + removes). Kept concise, no backend internals.
3. Auto-run sync (Pushing css changes for mattermost docs #3) — Subsection renamed from Auto-run sync on team admin policy creation to Automatic sync on policy changes. Body rewritten to state sync runs on any policy creation or rule/channel/active-state change. Removed the "auto-add or sync behavior enabled" gating language.
4. End-user copy (Fixing css issue #4) — Restricted file attachments section now reads: "Restricted attachments appear in messages with the placeholder Files not available and the subtitle Access to files is restricted based on attributes." Kept short. Admin-facing :ref: cross-link preserved.
5. Final cleanup (Changing css file name #5) — Grepped all five changed docs for NOT PRESENT IN PR, TODO, JIRA, MM-####, SCREENSHOT NEEDED, "reviewer note" — zero matches in published docs content. PR numbers / reviewer notes remain only in the PR description itself, where they belong.

Build / link check

Could not be run in the Claude sandbox — pipenv and sphinx-build are still not installed here (only make is). Same constraint noted in the original PR description. Please run make html and make linkcheck locally before merge to verify the :ref: anchors still resolve cleanly:

• administration-guide/manage/admin/abac-system-wide-policies:permission policies
• administration-guide/manage/admin/abac-channel-access-rules:manage team-scoped membership policies in team settings
• end-user-guide/collaborate/share-files-in-messages:restricted file attachments

Updated PR summary (drop-in for the PR description)

Cohesive v11.7 ABAC docs update.

• ABAC overview: "ABAC can be used with" framing for system-wide access, permission, team-scoped membership, and channel-specific access policies; clarifies who manages each.
• System-wide policies: Unique-name validation note for parent policies and new Permission policies section covering attribute-based file upload / file download restrictions.
• Channel access rules: New Manage team-scoped membership policies in Team Settings section. Covers the Team Admin workflow via the Membership Policies tab, the manage_team_access_rules permission, Team Settings sync status footer (Last sync time, Sync now), team-scope sync limits, Sync behavior by channel type (public = advisory/add-only; private = enforced/can remove), and Automatic sync on policy changes triggered by rule/channel/active-state changes. Team-scoped policies can be assigned to both public and private channels.
• Share files in messages: Short Restricted file attachments end-user note that references the actual UI placeholder strings Files not available / Access to files is restricted based on attributes.
• Permissions reference: manage_team_access_rules added to the permission table and to the team_admin built-in role.

Remaining reviewer notes (PR-description-only)

• Tab label: Still using Membership Policies for the Team Settings tab throughout. Reconcile against a v11.7.0 test instance before merge if the final shipped UI label differs.
• SCREENSHOT NEEDED: Capture Team Settings → Membership Policies area from a v11.7.0 test instance, including the sync status footer.
• Build / link check: make html and make linkcheck not runnable in the Claude sandbox (no pipenv / sphinx-build). Please run locally before merge.
• Coderabbit nitpick (not applied per scope): Promoting the team-scope sync constraint sentence to a .. important:: admonition was outside the targeted cleanup scope and was intentionally skipped. Easy to apply in a follow-up if desired.
  | Branch: claude/issue-8950-20260511-2015

[Combs7th]

@pvev - Does this look better?

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 5c402bd