11.7: Document ABAC permission policies and team-scoped membership policy workflows

[Combs7th]

@claude - Let's update the Mattermost Product Documentation to reflect the ABAC policy management workflow experience from Mattermost v11.7.0 onward captured via the following PRs:

• [MM-68183] Permission policies mattermost#36003 — MM-68183 Permission policies
• Feature mm 64509 team admin abac channels mattermost#36061 — Feature MM-64509 team admin ABAC channels
• MM 67594 - policies CUD operations to team settings modal channels ABAC mattermost#35590 — MM-67594 policies CUD operations to Team Settings modal channels ABAC
• MM-67967 add sync status footer to team settings mattermost#35729 — MM-67967 add sync status footer to Team Settings
• MM-63848: Enforce unique names for parent access control policies mattermost#35676 — MM-63848 enforce unique names for parent access control policies
• MM-68499 - auto run sync jobs on team admin abac policy creation mattermost#36276 — MM-68499 auto-run sync jobs on team admin ABAC policy creation

Goal:
Create one cohesive docs update PR, not separate docs PRs, because these PRs all affect the same ABAC/policy documentation area and should read as one unified admin workflow.

Scope and constraints:

• Do not modify changelogs, upgrade notes, version archives, deprecated/removed feature docs, or unsupported-release docs.
• Focus only on end-user/admin-facing Mattermost Product Documentation at docs.mattermost.com.
• Do not document implementation details, backend architecture, algorithms, internal API mechanics, database migrations, or test coverage.
• Do document visible admin behavior, user-visible file access effects, validation messages/constraints, sync status/actions, and required permissions where relevant.
• Use Mattermost v11.7.0 as the version because the linked PR metadata uses the v11.7.0 milestone.
• Keep the update minimal and workflow-focused.

Required doc touchpoints:

1. Update the main Attribute-Based Access Control overview page:

   • Mention that ABAC includes system-wide policies, team-scoped membership policies, channel-specific access rules, and permission policies where applicable.
   • Clarify who can manage each policy type: System Admins vs Team Admins vs Channel Admins, based only on PR evidence.

2. Update System-wide attribute-based access policies:

   • Add/adjust guidance for permission policies introduced in #36003.
   • Explain that permission policies can restrict file upload and file download behavior through ABAC.
   • Include only user/admin-visible behavior. Avoid API or implementation details.
   • Add a note that policy names must be unique for parent access control policies, and that duplicate names surface a user-friendly error, based on #35676.

3. Update or create a Team Settings / team-scoped ABAC membership policy section:

   • Document that Team Admins can create, edit, and delete channel membership policies directly from Team Settings when ABAC is enabled and they have the appropriate permission.
   • Document the Membership Policies / Access Policies tab naming exactly as confirmed in the current UI strings from the PRs.
   • Explain the Team Admin workflow at a high level: create policy, define attribute rules, assign applicable private channels, save, and review sync behavior.
   • Include the manage_team_access_rules permission only as an admin-facing permission requirement, not as an implementation detail.

4. Update sync behavior guidance:

   • Document the Team Settings sync status footer added in #35729, including last sync time and Sync now action.
   • Explain that team-scoped sync is limited to the team admin’s team scope.
   • Note that after team admin ABAC policy creation, sync jobs run automatically where auto-add/sync behavior applies, based on #36276.
   • Avoid describing job payloads, validation branches, or backend job architecture.

5. Add or update end-user-facing behavior only where necessary:

   • Briefly explain that users may see file attachments unavailable/redacted when file upload/download permission policies restrict access, based on #36003.
   • Do not create a large end-user page unless the existing docs structure clearly requires it. Prefer a short note in the most relevant existing ABAC or file-access section.

Output requirements:

• Provide a list of exact docs pages/files to update.
• Provide proposed before/after text or full replacement snippets for each touched section.
• Include a short PR summary and testing checklist for the docs PR.
• Keep the draft concise and avoid duplicating the same ABAC explanation across multiple pages.

[claude]

Claude finished @Combs7th's task in 5m 54s —— View job • claude/issue-8950-20260511-1952 • Create PR ➔

---

ABAC v11.7.0 Docs Update — done

• Read CLAUDE.md and explore repo structure
• Locate existing ABAC docs pages
• Find file-attachments / end-user docs for redaction note
• Find Team Settings docs location for team admin section
• Update attribute-based-access-control.rst overview (four policy types + who manages each)
• Update abac-system-wide-policies.rst (permission policies + unique-name validation)
• Add team-scoped Team Settings section in abac-channel-access-rules.rst
• Sync status footer + auto-run sync guidance (folded into team-scoped section)
• Add end-user file redaction note in share-files-in-messages.rst
• Add manage_team_access_rules row to permissions reference table + team_admin built-in role
• Commit and push

Files updated

File	Change
source/administration-guide/manage/admin/attribute-based-access-control.rst	Overview now lists 4 ABAC policy types (system-wide, permission, team-scoped, channel-specific) and clarifies who manages each (System / Team / Channel Admins).
source/administration-guide/manage/admin/abac-system-wide-policies.rst	Added note that parent policy names must be unique (#35676). Added new Permission policies section covering file upload / file download restrictions (#36003).
source/administration-guide/manage/admin/abac-channel-access-rules.rst	Added Manage team-scoped membership policies in Team Settings section: prerequisites, Team Admin workflow via the Access Policies tab, manage_team_access_rules permission requirement, Team Settings sync status footer (Last sync time, Sync now), team-scope sync limits, and auto-run sync on policy creation (#35590, #36061, #35729, #36276).
source/end-user-guide/collaborate/share-files-in-messages.rst	New short Restricted file attachments section noting that file uploads/downloads may be blocked or redacted under permission policies.
source/administration-guide/onboard/advanced-permissions-backend-infrastructure.rst	Added manage_team_access_rules row to the permission reference table; listed under the team_admin built-in role.

Touchpoint coverage from issue

1. ✅ Overview lists all four policy types and admin scopes.
2. ✅ System-wide doc covers permission policies (file upload/download), user-visible behavior only, and the unique-name validation note.
3. ✅ Team-scoped Team Settings section documents create/edit/delete from Team Settings; uses the Access Policies tab name; covers the create-policy → define rules → assign private channels → save → review sync workflow; calls out the manage_team_access_rules permission.
4. ✅ Sync footer (last sync time + Sync now), team-scope sync limits, and auto-run-on-creation behavior documented in the team-scoped section.
5. ✅ End-user note in share-files-in-messages.rst (short — added inline, no new page).

Suggested PR summary

Docs update for the v11.7 ABAC workflow. Covers: permission policies (file upload/download), team-scoped channel membership policies managed by Team Admins from Team Settings, the Access Policies tab, manage_team_access_rules permission, sync status footer with Sync now, auto-run sync on team-admin policy creation, unique-name enforcement for parent policies, and an end-user note on restricted file attachments.

Suggested testing checklist

• Sphinx build completes without new warnings or broken :ref: links for: abac-system-wide-policies:permission policies, abac-channel-access-rules:manage team-scoped membership policies in team settings, abac-channel-access-rules:team settings sync status footer, share-files-in-messages:restricted file attachments.
• ABAC overview page renders the four-policy-type bullet list and the System/Team/Channel admin breakdown.
• System-wide policies page renders the new 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, including the Team Settings sync status footer subsection.
• Share-files-in-messages page renders the Restricted file attachments section.
• Permissions reference table renders the new manage_team_access_rules row and team_admin role list includes the new permission.

Notes / caveats

• I couldn't fetch the linked mattermost/mattermost PR diffs directly (WebFetch unauthorized), so all UI strings, permission names, and behaviors come from the constraints encoded in the issue body. If any UI label (e.g., Access Policies vs Membership Policies tab) differs from the final shipped UI, those exact strings should be reconciled by a docs reviewer with PR access.
• I kept the team-scoped admin workflow in abac-channel-access-rules.rst rather than creating a new page, to avoid duplicating ABAC explanations across pages — per the "Keep the update minimal" constraint. Happy to split into a separate page if preferred.

Branch: claude/issue-8950-20260511-1952 ·

[Combs7th]

@claude - Please do one targeted cleanup/review pass on the ABAC v11.7.0 docs commit you just made.

Goal:
Keep the existing docs update mostly intact, but verify and clean up accuracy, naming, scope, and placement before the PR is opened for review.

Required checks:

1. Verify final UI labels

• Re-check the linked Mattermost PRs for the final shipped UI labels.
• Pay special attention to whether the Team Settings tab should be called “Access Policies” or “Membership Policies.”
• If the PRs conflict, prefer the latest/final UI string from the PR history or final merged code.
• Update the docs to use the final UI label consistently.
• If the final label cannot be confirmed, add a reviewer note:
  [NOT PRESENT IN PR — REQUIRES HUMAN JUDGMENT]

2. Verify permissions documentation placement

• Review the change made to:
  source/administration-guide/onboard/advanced-permissions-backend-infrastructure.rst
• Confirm this is the correct admin-facing place to document manage_team_access_rules.
• If this page is too backend/internal for the new permission, move or duplicate the permission note to the more appropriate admin permissions reference page.
• Do not over-document implementation details.

3. Tighten the “four policy types” framing

• Review the updated ABAC overview.
• Make sure it does not overstate the product model or imply four fully separate/equal feature areas if the PRs don’t support that.
• Prefer cautious wording such as:
  “ABAC can be used with system-wide policies, permission policies, team-scoped membership policies, and channel-specific access rules.”
• Avoid speculative architecture or product taxonomy language.

4. Re-check end-user file attachment note

• Confirm the short end-user note in:
  source/end-user-guide/collaborate/share-files-in-messages.rst
  is directly supported by #36003.
• Keep it brief.
• Do not create a larger end-user section unless the PR explicitly supports more user-facing behavior.
• Avoid overpromising exact UI states unless the PR shows the exact user-facing strings.

5. Screenshot readiness

• Do not add screenshots unless docs-quality screenshots are already available.
• Add a reviewer note in the PR description if screenshots should be captured later:
  [SCREENSHOT NEEDED — capture Team Settings Membership Policies area from v11.7.0 test instance]
• Recommended screenshot only if available:
  Team Settings → Membership Policies area, including sync status/footer if visible.

6. Build/link sanity

• Run the available docs build or link-check command if practical.
• Fix any broken refs, heading anchors, lint issues, or formatting problems caused by this commit.

Output:
After making cleanup edits directly, provide:

• Files changed in this cleanup pass.
• What changed and why.
• Any unresolved reviewer notes.
• Updated PR summary.
• Updated testing checklist.

Constraints:

• Do not rewrite the whole docs update.
• Do not add new scope.
• Do not modify changelogs, upgrade notes, version archives, deprecated/removed feature docs, or unsupported-release docs.
• Keep all changes admin/end-user facing.
• Avoid implementation details.

[claude]

Claude finished @Combs7th's task in 6m 53s —— View job • claude/issue-8950-20260511-2002

---

ABAC v11.7.0 Docs — Cleanup-pass applied

This run was triggered on a fresh branch (claude/issue-8950-20260511-2002), separate from the prior run's branch (claude/issue-8950-20260511-1952). I couldn't fetch the prior branch or the upstream mattermost/mattermost PRs from this environment (WebFetch and most git fetch / cross-repo gh api calls were denied). So I re-applied the full v11.7 ABAC docs update on this branch with the cleanup-pass guidance from your trigger comment baked in from the start, rather than as a follow-up diff.

Create a PR ➔

Files changed (5)

File	Change
source/administration-guide/manage/admin/attribute-based-access-control.rst	Overview reworded to cautious "ABAC can be used with the following policy types" framing covering system-wide access, permission, team-scoped membership, and channel-specific access policies. Added Team Admins can: sub-list under "Configure access policies".
source/administration-guide/manage/admin/abac-system-wide-policies.rst	Added unique-name validation note to step 2 of "Define access control policies" (#35676). Added new Permission policies section covering file upload / file download restrictions with cross-link to the end-user note (#36003).
source/administration-guide/manage/admin/abac-channel-access-rules.rst	Added Manage team-scoped membership policies in Team Settings section with Prerequisites, Team Admin workflow, Team Settings sync status footer, and Auto-run sync on team admin policy creation subsections. Permission manage_team_access_rules documented as admin-facing prerequisite. [NOT PRESENT IN PR — REQUIRES HUMAN JUDGMENT] note flags Access Policies vs Membership Policies tab label (#35590, #36061, #35729, #36276).
source/end-user-guide/collaborate/share-files-in-messages.rst	New short Restricted file attachments section noting attribute-based permission policies may block/redact uploads or downloads, with cross-link to the admin-facing Permission policies section (#36003). No new page, no overpromise of UI strings.
source/administration-guide/onboard/advanced-permissions-backend-infrastructure.rst	Added manage_team_access_rules row to permission table (team scope) and to team_admin built-in role list. Placement matches the existing manage_channel_access_rules pattern — same page is the canonical permission reference for sibling ABAC permissions.

Cleanup-pass items addressed

1. UI labels — Could not directly access the source PRs to confirm the final tab label. The trigger comment / issue body reference both Access Policies and Membership Policies. Drafted text uses Access Policies and adds an explicit [NOT PRESENT IN PR — REQUIRES HUMAN JUDGMENT] reviewer note. Recommend a docs reviewer with PR access reconcile both occurrences before merge.
2. Permissions doc placement — Kept manage_team_access_rules in advanced-permissions-backend-infrastructure.rst. Verified this is the existing convention: sibling manage_channel_access_rules is documented on the same page in both the permission reference table and the team_admin / channel_admin role lists. The advanced-permissions.rst page is conceptual and does not list individual permission names.
3. Four policy types framing — Replaced "ABAC provides 2 levels of control" / "ABAC includes ..." with cautious "ABAC can be used with the following policy types" wording, avoiding any speculative product-taxonomy claims.
4. End-user file attachment note — Kept to a short two-paragraph section, no new page, no exact UI string claims beyond "unavailable or redacted". Directly tied to #36003 file upload/download permission policies.
5. Screenshots — None added. Flagged [SCREENSHOT NEEDED — capture Team Settings Membership Policies area from v11.7.0 test instance] in the suggested PR description above.
6. Build/link sanity — Local Sphinx build not runnable here (pipenv / sphinx-build not installed in this sandbox). Verified heading text/underline lengths match for all new sections; all new :ref: targets reference existing or newly-added headings. Listed the three new ref anchors in the suggested testing checklist so a reviewer can run make html / make linkcheck locally.

Unresolved reviewer notes

• [NOT PRESENT IN PR — REQUIRES HUMAN JUDGMENT] — Team Settings tab label: Access Policies vs Membership Policies. Drafted as Access Policies with inline note; reconcile against v11.7.0 UI.
• [SCREENSHOT NEEDED — capture Team Settings Membership Policies area from v11.7.0 test instance] — including the sync status footer if visible.
• Local Sphinx build was not run. Reviewer should run make html and make linkcheck locally.
  · Branch: claude/issue-8950-20260511-2002

[Combs7th]

@claude - Please do one final pre-PR cleanup on the current branch.

Do not re-apply the whole docs update and do not create a new branch. Work only from the current branch/diff.

Tasks:

1. Remove any [NOT PRESENT IN PR — REQUIRES HUMAN JUDGMENT] notes from the actual docs content. Move unresolved items to the PR description/reviewer notes only.
2. For the Team Settings tab label, use “Membership Policies” unless the current docs branch or available PR evidence clearly shows the final UI label is “Access Policies.”
3. Make sure there are no internal reviewer notes, issue references, or PR-number callouts in the published docs text unless that is normal Mattermost docs style.
4. Keep the screenshot note only in the PR description, not in docs content.
5. Run or attempt the docs build/link check if available. If unavailable, note that in the PR description only.
6. Provide the final files changed, remaining reviewer notes, and final PR summary.

[claude]

Claude finished @Combs7th's task in 6m 34s —— View job • claude/issue-8950-20260511-2015

---

ABAC v11.7.0 Docs — Final Pre-PR Cleanup applied

This task was triggered on a fresh branch (claude/issue-8950-20260511-2015) that had no prior diff against master — the prior runs' commits live on separate claude/issue-8950-* branches, and the sandbox blocks git fetch, gh api, and WebFetch against them. I couldn't preserve the prior branch's diff incrementally, so I applied the full v11.7 ABAC docs update on this branch with all of your cleanup-pass tasks baked in from the start (no [NOT PRESENT IN PR …] notes anywhere in docs, Membership Policies tab label, no PR/issue numbers in docs, no screenshot note in docs).

• Apply the docs update on the current branch
• Use Membership Policies as the Team Settings tab label
• Remove [NOT PRESENT IN PR — REQUIRES HUMAN JUDGMENT] notes from docs content
• Strip reviewer notes / issue refs / PR-number callouts from published docs
• Keep screenshot note in PR description only
• Attempt docs build / link check (pipenv / sphinx-build not installed in this sandbox — noted in PR description)
• Commit and push

Create a PR ➔

Files changed (5)

File	Change
source/administration-guide/manage/admin/attribute-based-access-control.rst	Overview reworded to cautious "ABAC can be used with the following policy types" framing covering system-wide access, permission, team-scoped membership, and channel-specific access policies. Added Team Admins can: sub-list under "Configure access policies". No PR/issue refs in body.
source/administration-guide/manage/admin/abac-system-wide-policies.rst	Added unique-name validation note to step 2 of "Define access control policies". Added new Permission policies section covering attribute-based file upload / file download restrictions with cross-link to the end-user note. No PR/issue refs in body.
source/administration-guide/manage/admin/abac-channel-access-rules.rst	Added Manage team-scoped membership policies in Team Settings section with Prerequisites, Team Admin workflow via the Membership Policies tab, manage_team_access_rules permission requirement, Team Settings sync status footer (Last sync time, Sync now), team-scope sync limits, and Auto-run sync on team admin policy creation. No reviewer notes / PR refs / [NOT PRESENT IN PR] markers anywhere in body.
source/end-user-guide/collaborate/share-files-in-messages.rst	New short Restricted file attachments section noting that attribute-based permission policies may block or redact uploads/downloads, with a cross-link to the admin-facing Permission policies section. No new page; no exact-UI-string overpromises.
source/administration-guide/onboard/advanced-permissions-backend-infrastructure.rst	Added manage_team_access_rules row to the permission table (team scope) and added manage_team_access_rules to the team_admin built-in role list. Placement matches the existing manage_channel_access_rules pattern.

Cleanup-pass items addressed

1. Reviewer notes removed from docs content — verified via grep that none of the changed files contain NOT PRESENT IN PR, SCREENSHOT NEEDED, PR numbers (#36003, #36061, #35590, #35729, #35676, #36276), MM Jira IDs (MM-6…), or mattermost/mattermost# callouts.
2. Tab label — used Membership Policies consistently throughout abac-channel-access-rules.rst and attribute-based-access-control.rst per cleanup guidance. No "Access Policies" label remains in any new content.
3. Internal callouts — no internal reviewer notes, issue refs, or PR-number callouts in the published docs body.
4. Screenshot note — kept only in this comment and in the prefilled PR description, not in docs content.
5. Build / link check — could not run locally; pipenv / sphinx-build are not installed in this Claude sandbox, and pip install is denied. Noted explicitly in the prefilled PR description. Manually verified that all new heading underlines match their title lengths and that autosectionlabel_prefix_document = True in source/conf.py produces the :ref: anchors I used.

Remaining reviewer notes (PR description only)

• Tab label reconciliation — confirm Membership Policies matches the final v11.7.0 UI tab string before merge.
• Screenshot capture — Team Settings → Membership Policies area, including sync status footer if visible.
• Local build verification — run make html and make linkcheck before merge; the three new :ref: anchors are listed in the PR description for spot-checking.

Final PR summary

Cohesive v11.7 ABAC docs update. Covers system-wide access, permission, team-scoped membership, and channel-specific access policy types and who manages each; adds the Permission policies section (file upload / download restrictions); documents the Team Admin workflow in Team Settings → Membership Policies including the sync status footer, Sync now, team-scope sync limits, and auto-run sync on team admin policy creation; adds the unique-name validation note for parent policies; adds a short end-user note on restricted file attachments; and adds manage_team_access_rules to the permissions reference and the team_admin built-in role.
· Branch: claude/issue-8950-20260511-2015