Add consolidated "Install and manage plugins" documentation#9073
Add consolidated "Install and manage plugins" documentation#9073ewwollesen wants to merge 2 commits 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). |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughAdds a new plugin management guide, updates the administration guide index to include it, and adds a cross-reference from the integrations guide’s pre-built plugins section. 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
|
Newest code from mattermost has been published to preview environment for Git SHA 7ab0e6b |
- Use the full PluginSettings.EnableUploads config path to avoid ambiguity
- Reword the disable note to describe the observable effect ("stops the
plugin from running") instead of "logs it out of all sessions"
- Document what removal does to plugin data: configuration and KV store data
are preserved, bot accounts stay active, and removal is effectively
reversible. Verified against the server source.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Newest code from mattermost has been published to preview environment for Git SHA 4c53e1b |
jadrales
left a comment
jadrales
left a comment
There was a problem hiding this comment.
Formatting LGTM. I left a few comments regarding some small changes we can consider for the Manage Plugins page, but overall I think this will be a great addition to the admin docs.
|
|
||
| Upload a plugin bundle when you're installing a custom or third-party plugin that isn't in the Marketplace, or when your server runs in an air-gapped or restricted environment. Uploading requires the **Upload Plugin** setting to be enabled and the **Require plugin signature** setting to be disabled. | ||
|
|
||
| 1. Download the plugin bundle. Mattermost plugins are distributed as ``.tar.gz`` files, typically from the plugin's GitHub releases page. |
There was a problem hiding this comment.
I think it would be valuable to add something that mentions to download the package for their specific OS, since that can be a common issue for the plugin upload not working. In general, I might rephrase to something like:
Download the plugin bundle
.tar.gzfor your specific OS from the plugin's GitHub releases page.
|
|
||
| The :doc:`mmctl command line tool </administration-guide/manage/mmctl-command-line-tool>` is useful for scripted or remote plugin management. Plugins must be enabled in the server configuration first. | ||
|
|
||
| - Install the latest version from the Marketplace by plugin ID: |
There was a problem hiding this comment.
Wondering if we should provide some guidance on how to grab the plugin ID? For most plugins it's usually just the name of the plugin (e.g. jira), but others have less of a straightforward ID (e.g. Calls has an ID of com.mattermost.calls rather than just calls). We could add a quick one-liner here about checking the plugin's plugin.json for this, unless there's an easier/better way to grab that info
| 2. In the **Installed Plugins** list, locate the plugin. | ||
| 3. Select **Enable** or **Disable**. | ||
|
|
||
| To enable or disable a plugin with mmctl: |
There was a problem hiding this comment.
It might be helpful to have some subheaders here, so you can directly link others to specific sections on how to enable/disable plugins, similar to how "Install a Plugin" is set up. For example, we could have a subheader for From the System Console and one for Using mmctl for a structure like:
Enable or disable a plugin
From the System Console
Using mmctl
I'm like 1/5 on this though so we can leave as-is if we think that the extra headers won't provide much value
|
|
||
| We recommend keeping plugins up to date as new versions are released. Updates are generally seamless and don't interrupt the user experience, but you should review each plugin's release notes for compatibility considerations, and test updates in a staging environment before applying them in production. | ||
|
|
||
| You can update a plugin using any of the following methods: |
There was a problem hiding this comment.
Similar feedback as before, I wonder if having subheaders/sections would be beneficial here for easier linking. Still like 1/5 on it though.
|
|
||
| Removing a plugin disables it and uninstalls it from the server. | ||
|
|
||
| To remove a plugin in the System Console: |
There was a problem hiding this comment.
Same feedback as before regarding subsections.
|
|
||
| .. note:: | ||
|
|
||
| Removing a plugin uninstalls it from the server and stops it from running, but Mattermost preserves the plugin's associated data: |
There was a problem hiding this comment.
Is there any guidance on how this data can be fully cleared/deleted that we can add here in the event that that removal is a want or requirement for an instance?
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