Add consolidated "Install and manage plugins" documentation#9073
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 as they are similar to previous changes (1)
📝 WalkthroughWalkthroughAdds a plugin management guide covering the plugin lifecycle, links it from the administration index, and references it from the integrations guide. 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.
There was a problem hiding this comment.
Added download guidance here in 648cd72, with one tweak worth flagging: looking at the plugin build system, standard Mattermost bundles package the server binaries for all supported platforms in a single .tar.gz (the manifest's server.executables map), and the server auto-selects the matching one at load. So "download for your OS" isn't quite accurate as blanket advice. I worded it so the per-platform caveat applies only when a plugin publishes separate per-OS assets. If the upload failures you've seen trace to something more specific, let me know and I'll capture that instead.
There was a problem hiding this comment.
Correction to my note above — you were right. I checked the actual release assets (Calls v1.12.2, plus GitHub/GitLab/Jira) and they do publish per-platform bundles alongside the universal one, with the per-platform ones much smaller (Calls: 31 MB linux-amd64 vs 92 MB universal). My earlier check only looked at the default build target and missed the released per-platform assets, so your original point stands. Reworded step 1 in 4e2316b to recommend the bundle matching the server's OS/architecture (a mismatched one won't start), with the universal bundle as the auto-selecting fallback.
|
|
||
| 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
There was a problem hiding this comment.
Added in 648cd72 — the mmctl section now explains that a plugin's ID is the id value in its plugin.json, often the plugin name (github, playbooks) but sometimes a reverse-DNS identifier like com.mattermost.calls for Calls, and that mmctl plugin list shows the IDs of installed plugins. Thanks — and thanks to @esethna for the +1.
| 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
There was a problem hiding this comment.
I think it's fine as is given the content isn't very long, so it's easy enough to scan for the method the reader is looking for.
|
|
||
| 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.
There was a problem hiding this comment.
Same as above: I think it's fine as is given the content isn't very long, so it's easy enough to scan for the method the reader is looking for.
|
|
||
| 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?
There was a problem hiding this comment.
Added a note in 648cd72. Confirmed against the server source: removing a plugin disables it and deletes the bundle, but intentionally retains its config, KV store data, and any bot accounts — and there's no supported System Console or mmctl command to fully purge that data. Clearing it requires direct database changes, so the note points admins to Mattermost support rather than documenting raw table edits. If you'd prefer we spell out the specific tables, I can expand it.
| - **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** (``PluginSettings.EnableUploads``) must be set to **true** to upload plugin bundles from your local computer. This setting applies to self-hosted deployments only. | ||
| - **Require plugin signature**, when enabled, validates plugin signatures and **disables plugin file uploads** in the System Console. With this setting enabled, install plugins from the Marketplace or as pre-packaged plugins instead. |
There was a problem hiding this comment.
This last one re plugin signature maybe not needed for this section?
There was a problem hiding this comment.
Agreed — removed it from Before you begin in 648cd72. It's still covered in the Plugin upload section, where the signature/upload interaction is directly relevant.
| - **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** (``PluginSettings.EnableUploads``) must be set to **true** to upload plugin bundles from your local computer. This setting applies to self-hosted deployments only. |
There was a problem hiding this comment.
Can we be consistent about including the plugin variable like this with all the settings mentioned in this doc (whenever it is mentioned for the first time)?
There was a problem hiding this comment.
Good call — done in 648cd72. Each plugin setting now shows its PluginSettings.* key on first mention: Enable, EnableMarketplace, EnableRemoteMarketplace, EnableUploads, AutomaticPrepackagedPlugins, and RequirePluginSignature (now introduced in the Plugin upload section, since the prerequisite bullet was removed per your other comment).
|
|
||
| See the :doc:`plugins configuration settings </administration-guide/configure/plugins-configuration-settings>` documentation for details on each of these settings, including their ``config.json`` paths and environment variables. | ||
|
|
||
| Install a plugin |
There was a problem hiding this comment.
Propose: "Plugin installation methods"
Then each nested section can be "App Marketplace" "Plugin Upload" "mmctl"
There was a problem hiding this comment.
Done in 648cd72 — the section is now Plugin installation methods with App Marketplace / Plugin upload / mmctl subsections. I kept App Marketplace capitalized since it's the literal menu name, and used sentence case for Plugin upload to match our heading style guide. Happy to switch it to Plugin Upload if you'd rather all three read as title case.
|
|
||
| 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: |
| 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.
I think it's fine as is given the content isn't very long, so it's easy enough to scan for the method the reader is looking for.
|
|
||
| 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.
Same as above: I think it's fine as is given the content isn't very long, so it's easy enough to scan for the method the reader is looking for.
|
Thanks @ewwollesen, nice doc, some feedback provided ^ |
- Show PluginSettings.* config keys consistently on first mention - Rename to Plugin installation methods with App Marketplace, Plugin upload, and mmctl subsections - Drop the Require plugin signature bullet from prerequisites - Add plugin ID guidance and an accurate multi-platform bundle note - Note that removed-plugin config/KV data isn't purged by supported tooling - Add an mmctl --force caution and a post-install verification step 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 648cd72 |
Guide admins to download the bundle matching their server's OS and architecture (smaller, and a mismatched-platform bundle won't start), with the universal bundle as the auto-selecting fallback. 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 4e2316b |
|
LGTM |
|
Newest code from mattermost has been published to preview environment for Git SHA e60b7b9 |
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