Add consolidated "Install and manage plugins" documentation#9073
Add consolidated "Install and manage plugins" documentation#9073ewwollesen wants to merge 1 commit into
Conversation
Adds a plugin-agnostic admin guide covering installing (Marketplace, manual upload, and mmctl), enabling/disabling, configuring, updating, and removing plugins. This guidance was previously scattered across per-plugin pages and configuration references with no consolidated how-to. - New page: administration-guide/configure/manage-plugins.rst - Registered in the server-configuration toctree and bullet list - Added a discovery pointer from integrations-guide/plugins.rst Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a consolidated, plugin-agnostic admin guide that documents the full Mattermost plugin lifecycle (install/enable/configure/update/remove) and wires it into existing navigation so admins can find it from both the Integrations and Administration guides.
Changes:
- Adds a new “Install and manage plugins” admin page covering lifecycle tasks via System Console and
mmctl. - Links the new page from the Integrations plugins overview for better discovery.
- Registers the new page in the Server configuration hub navigation.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| source/integrations-guide/plugins.rst | Adds a discovery link pointing admins to the new consolidated plugin-management guide. |
| source/administration-guide/manage/admin/server-configuration.rst | Wires the new guide into the Server configuration hub toctree and topic list. |
| source/administration-guide/configure/manage-plugins.rst | Introduces the consolidated plugin lifecycle documentation (System Console + mmctl). |
| - **Enable plugins** must be set to **true** (the default) for the plugin system to work. When disabled, all plugins are turned off. | ||
| - **Enable Marketplace** must be set to **true** (the default) to install plugins from the in-product Marketplace. | ||
| - **Enable remote Marketplace** must be set to **true** (the default) for the Marketplace to connect to the remote endpoint and list community and Mattermost-provided plugins. Set this to **false** for servers that can't reach the internet; the Marketplace then shows only pre-packaged and installed plugins. | ||
| - **Upload Plugin** (``EnableUploads``) must be set to **true** to upload plugin bundles from your local computer. This setting applies to self-hosted deployments only. |
|
|
||
| .. note:: | ||
|
|
||
| Disabling a plugin immediately removes it from the user interface and logs it out of all sessions. The plugin remains installed and can be re-enabled at any time. |
📝 WalkthroughWalkthroughAdds a new administration guide for managing plugins, updates the server administration guide index to surface it, and links the integrations guide’s pre-built plugins section to the new page. ChangesPlugin management documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (5)
source/administration-guide/configure/manage-plugins.rst (5)
126-132: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd cautionary context for the
--forceflag.The
--forceflag overwrites the existing plugin without confirmation. Consider adding a brief warning that this is destructive and cannot be undone from the CLI—admins should verify the new bundle's compatibility and ideally test in staging first (as noted in the preceding paragraph). A one-sentence caution after the code block suffices.🤖 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/configure/manage-plugins.rst` around lines 126 - 132, The documentation for mmctl plugin updates via the --force flag needs a cautionary warning. In the manage-plugins.rst section around the mmctl plugin add/install-url examples, add one sentence after the code block stating that --force overwrites the existing plugin without confirmation, is destructive and cannot be undone from the CLI, and should only be used after verifying compatibility and preferably testing in staging first.Source: Coding guidelines
39-43: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd a success check after the Marketplace install steps.
After step 3, consider adding a brief verification step such as confirming the plugin appears in Plugins > Plugin Management with a Running status, or that the plugin's features are visible in the user interface. This helps novice administrators verify progress and builds confidence that the installation succeeded.
🤖 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/configure/manage-plugins.rst` around lines 39 - 43, Add a short post-install verification step after the Marketplace install instructions in manage-plugins.rst. Update the numbered steps around the App Marketplace workflow so administrators are told to confirm the plugin appears in Plugins > Plugin Management with a Running status, or otherwise verify its features are available in the UI. Keep the wording concise and place it immediately after the current install/configure/enable steps.Source: Coding guidelines
52-52: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick winElevate the security framing for disabling signature validation.
The instruction to disable Require plugin signature is a security-sensitive prerequisite. Consider wrapping this requirement in an
.. important::admonition that briefly explains: signature validation protects against unverified plugins; disable it only when installing trusted custom plugins, and re-enable it afterward. This follows the guidance to use stronger admonition levels when the consequence involves security exposure.🤖 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/configure/manage-plugins.rst` at line 52, The plugin upload guidance in the documentation should treat disabling Require plugin signature as a security-sensitive action; update the section around the plugin upload instructions to place the signature-validation requirement inside an important admonition, and explicitly note that signature validation protects against unverified plugins, should only be disabled for trusted custom plugins, and should be re-enabled afterward. Use the manage-plugins documentation section and the Upload Plugin / Require plugin signature settings text as the anchors for the change.Source: Coding guidelines
63-87: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd brief scenario guidance for each mmctl install variant.
Novice administrators may not know when to choose
marketplace install,add, orinstall-url. Consider adding one sentence before each bullet explaining the scenario: Marketplace for pre-built plugins with known IDs,addfor local custom bundles, andinstall-urlfor remote custom bundles. Also briefly explain how to find a plugin's ID (e.g., from the Marketplace listing or the plugin bundle metadata).🤖 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/configure/manage-plugins.rst` around lines 63 - 87, The mmctl plugin install examples in manage-plugins.rst need brief scenario guidance for choosing between the three install variants. Update the documentation around the mmctl plugin marketplace install, mmctl plugin add, and mmctl plugin install-url examples to add one short sentence before each bullet explaining when to use it, and include a concise note on where to find a plugin ID such as in the Marketplace listing or bundle metadata.Source: Coding guidelines
17-24: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick winStrengthen security framing for upload-related settings.
The prerequisite bullets at lines 17–23 present Upload Plugin and Require plugin signature as neutral configuration steps. Disabling signature validation to enable uploads introduces a meaningful security trade-off. Consider adding an
.. important::admonition after this list that briefly advises enabling uploads only when needed and keeping signature validation enabled otherwise. This aligns with the principle of least privilege for service exposure in documentation guidance.🤖 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/configure/manage-plugins.rst` around lines 17 - 24, The configuration bullets in manage-plugins.rst describe upload-related settings too neutrally; add an admonition after the list near the Upload Plugin and Require plugin signature entries to make the security trade-off explicit. Use the existing documentation structure around the plugin settings section to note that uploads should be enabled only when needed and signature validation should remain enabled by default unless there is a clear operational need. Keep the guidance brief and tied to the plugin upload workflow so readers understand the least-privilege recommendation.Source: Coding guidelines
🤖 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/configure/manage-plugins.rst`:
- Around line 139-154: Clarify the “Remove a plugin” section by documenting what
Mattermost actually does with plugin-related data when using the Remove action
or mmctl plugin delete in manage-plugins.rst. Update the Remove a plugin
guidance to explicitly state whether plugin configuration, KV store data, and
bot accounts are preserved, disabled, or permanently deleted, and whether
removal is reversible; use the existing “Remove a plugin” heading and the System
Console/mmctl instructions as the place to add this behavior note.
---
Nitpick comments:
In `@source/administration-guide/configure/manage-plugins.rst`:
- Around line 126-132: The documentation for mmctl plugin updates via the
--force flag needs a cautionary warning. In the manage-plugins.rst section
around the mmctl plugin add/install-url examples, add one sentence after the
code block stating that --force overwrites the existing plugin without
confirmation, is destructive and cannot be undone from the CLI, and should only
be used after verifying compatibility and preferably testing in staging first.
- Around line 39-43: Add a short post-install verification step after the
Marketplace install instructions in manage-plugins.rst. Update the numbered
steps around the App Marketplace workflow so administrators are told to confirm
the plugin appears in Plugins > Plugin Management with a Running status, or
otherwise verify its features are available in the UI. Keep the wording concise
and place it immediately after the current install/configure/enable steps.
- Line 52: The plugin upload guidance in the documentation should treat
disabling Require plugin signature as a security-sensitive action; update the
section around the plugin upload instructions to place the signature-validation
requirement inside an important admonition, and explicitly note that signature
validation protects against unverified plugins, should only be disabled for
trusted custom plugins, and should be re-enabled afterward. Use the
manage-plugins documentation section and the Upload Plugin / Require plugin
signature settings text as the anchors for the change.
- Around line 63-87: The mmctl plugin install examples in manage-plugins.rst
need brief scenario guidance for choosing between the three install variants.
Update the documentation around the mmctl plugin marketplace install, mmctl
plugin add, and mmctl plugin install-url examples to add one short sentence
before each bullet explaining when to use it, and include a concise note on
where to find a plugin ID such as in the Marketplace listing or bundle metadata.
- Around line 17-24: The configuration bullets in manage-plugins.rst describe
upload-related settings too neutrally; add an admonition after the list near the
Upload Plugin and Require plugin signature entries to make the security
trade-off explicit. Use the existing documentation structure around the plugin
settings section to note that uploads should be enabled only when needed and
signature validation should remain enabled by default unless there is a clear
operational need. Keep the guidance brief and tied to the plugin upload workflow
so readers understand the least-privilege recommendation.
🪄 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: 351d071e-5750-4ece-b95f-7ced2056816e
📒 Files selected for processing (3)
source/administration-guide/configure/manage-plugins.rstsource/administration-guide/manage/admin/server-configuration.rstsource/integrations-guide/plugins.rst
| Remove a plugin | ||
| --------------- | ||
|
|
||
| Removing a plugin disables it and uninstalls it from the server. | ||
|
|
||
| To remove a plugin in the System Console: | ||
|
|
||
| 1. Go to **Plugins > Plugin Management**. | ||
| 2. In the **Installed Plugins** list, locate the plugin. | ||
| 3. Select **Remove**. | ||
|
|
||
| To remove a plugin with mmctl: | ||
|
|
||
| .. code-block:: sh | ||
|
|
||
| mmctl plugin delete <id> |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Clarify data retention behavior when removing a plugin.
The documentation states that removing a plugin "disables it and uninstalls it from the server" without explaining whether plugin configuration, KV store data, or bot accounts are preserved or permanently deleted. Admins need this information to assess whether removal is reversible and whether to back up configuration first. Please verify the actual Mattermost behavior and document it explicitly.
🤖 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/configure/manage-plugins.rst` around lines 139 -
154, Clarify the “Remove a plugin” section by documenting what Mattermost
actually does with plugin-related data when using the Remove action or mmctl
plugin delete in manage-plugins.rst. Update the Remove a plugin guidance to
explicitly state whether plugin configuration, KV store data, and bot accounts
are preserved, disabled, or permanently deleted, and whether removal is
reversible; use the existing “Remove a plugin” heading and the System
Console/mmctl instructions as the place to add this behavior note.
|
Newest code from mattermost has been published to preview environment for Git SHA 7ab0e6b |
Summary
Adds a consolidated, plugin-agnostic admin guide for the full plugin lifecycle. Previously this guidance was scattered across per-plugin install pages (Boards, Legal Hold, Channel Export, Agents, etc.) and configuration references, with no single "how do I install/update/remove a plugin" page.
What's included
New page
administration-guide/configure/manage-plugins.rst("Install and manage plugins") covering:mmctl.mmctl plugin add -f), and Remove.The page links out to the existing reference pages (plugins configuration settings, mmctl, plugins overview, popular integrations) rather than duplicating them.
Wiring
server-configuration.rsthub (toctree + bullet list), next to the Boards entry.integrations-guide/plugins.rst.Build
Incremental
gmake htmlsucceeds with no new warnings; the page renders tomanage-plugins.html.Notes for reviewers
integrations-guide/plugins.rst). Happy to addall-commercialif preferred.administration-guide/configure/alongsideinstall-boards.rst; open to relocating ifintegrations-guide/is a better home.🤖 Generated with Claude Code