Skip to content

Reorganize experimental configuration settings based on access tags #8728

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cwarnermm wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Reorganize experimental configuration settings based on access tags #8728

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ef9a2b3
Reorganize experimental configuration settings based on access tags
github-actions[bot] Feb 6, 2026
0487a6e
Fix RST table formatting issues in experimental and environment confi…
github-actions[bot] Apr 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 98 additions & 0 deletions source/administration-guide/configure/authentication-configuration-settings.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1712,6 +1712,47 @@ Login button text
| String input. Default is **SAML**. | - Environment variable: ``MM_SAMLSETTINGS_LOGINBUTTONTEXT`` |
+---------------------------------------------------------------------------+-------------------------------------------------------------------+

config.json-only settings
^^^^^^^^^^^^^^^^^^^^^^^^^

The following SAML configuration settings are only available by editing the ``config.json`` file.

.. config:setting:: scoping-idp-provider-id
:displayname: Scoping IDP provider ID (SAML)
:systemconsole: N/A
:configjson: ScopingIDPProviderId
:environment: N/A
Comment on lines +1723 to +1724
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify where ScopingIDPProviderId / ScopingIDPName live in repo docs and source schema.
rg -n "ScopingIDPProviderId|ScopingIDPName|SamlSettings.*Scope|SamlSettings" -S

Repository: mattermost/docs

Length of output: 26427

Update :configjson: paths for SAML scoping settings to match page conventions

Lines 1723 and 1741 use bare keys (ScopingIDPProviderId, ScopingIDPName), inconsistent with all other SAML settings on this page which use the .SamlSettings.* prefix. Update both to:

  • Line 1723: :configjson: .SamlSettings.ScopingIDPProviderId
  • Line 1741: :configjson: .SamlSettings.ScopingIDPName
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In
`@source/administration-guide/configure/authentication-configuration-settings.rst`
around lines 1723 - 1724, Update the two SAML scoping configjson keys to use the
same prefix as other SAML settings: change the bare keys ScopingIDPProviderId
and ScopingIDPName to .SamlSettings.ScopingIDPProviderId and
.SamlSettings.ScopingIDPName respectively so the :configjson: entries align with
the rest of the page’s naming convention.

:description: Allows an authenticated user to skip the initial login page of their federated Azure AD server, and only require a password to log in.

Scoping IDP provider ID
~~~~~~~~~~~~~~~~~~~~~~~~

This setting isn't available in the System Console and can only be set in ``config.json``.

Allows an authenticated user to skip the initial login page of their federated Azure AD server, and only require a password to log in.

+---------------------------------------------------------------------------------------------+
| This feature's ``config.json`` setting is ``"ScopingIDPProviderId": ""`` with string input. |
+---------------------------------------------------------------------------------------------+

.. config:setting:: scoping-idp-provider-name
:displayname: Scoping IDP provider name (SAML)
:systemconsole: N/A
:configjson: ScopingIDPName
:environment: N/A
:description: Adds the name associated with a user's Scoping Identity Provider ID.

Scoping IDP provider name
~~~~~~~~~~~~~~~~~~~~~~~~~~

This setting isn't available in the System Console and can only be set in ``config.json``.

Adds the name associated with a user's Scoping Identity Provider ID.

+---------------------------------------------------------------------------------------+
| This feature's ``config.json`` setting is ``"ScopingIDPName": ""`` with string input. |
+---------------------------------------------------------------------------------------+

----

OAuth 2.0
Expand Down Expand Up @@ -1876,6 +1917,25 @@ GitLab OAuth 2.0 Token endpoint
| String input. | |
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------+

.. config:setting:: oauth-gitlabscope
:displayname: GitLab scope (OAuth - GitLab)
:systemconsole: N/A
:configjson: .GitLabSettings.Scope
:environment: MM_GITLABSETTINGS_SCOPE
:description: Standard setting for OAuth to determine the scope of information shared with the OAuth client. Not currently supported by GitLab OAuth.

GitLab scope
''''''''''''

This setting isn't available in the System Console and can only be set in ``config.json``.

+---------------------------------------------------------------+-------------------------------------------------------------+
| Standard setting for OAuth to determine the scope of | - System Config path: N/A |
| information shared with the OAuth client. | - ``config.json`` setting: ``GitLabSettings`` > ``Scope`` |
| | - Environment variable: ``MM_GITLABSETTINGS_SCOPE`` |
| String input. Not currently supported by GitLab OAuth. | |
Comment on lines +1930 to +1936
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

“config.json-only” wording contradicts documented environment variable support

These blocks state settings can “only be set in config.json”, but each also provides an environment variable mapping. That’s contradictory and can mislead admins.

Suggested minimal wording fix 
-This setting isn't available in the System Console and can only be set in ``config.json``.
+This setting isn't available in the System Console. Set it via ``config.json`` or the mapped environment variable.

Based on learnings: “Describe Mattermost feature behavior, UI labels, and capability boundaries accurately”.

Also applies to: 2053-2059, 2204-2210

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In
`@source/administration-guide/configure/authentication-configuration-settings.rst`
around lines 1930 - 1936, The document incorrectly says a setting "can only be
set in config.json" while the table lists an environment variable (e.g., the
GitLabSettings > Scope row); update the wording in the affected blocks to
accurately reflect both options (e.g., "This setting can be set in config.json
or via the corresponding environment variable") and apply the same change to the
other occurrences referenced (the blocks around lines 2053-2059 and 2204-2210)
so the System Console / config.json vs environment variable guidance is
consistent.

+---------------------------------------------------------------+-------------------------------------------------------------+

Google OAuth 2.0 settings
^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -1980,6 +2040,25 @@ Google OAuth 2.0 Token endpoint
| String input. | - Environment variable: ``MM_GOOGLESETTINGS_TOKENENDPOINT`` |
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+

.. config:setting:: oauth-googlescope
:displayname: Google scope (OAuth - Google)
:systemconsole: N/A
:configjson: .GoogleSettings.Scope
:environment: MM_GOOGLESETTINGS_SCOPE
:description: Standard setting for OAuth to determine the scope of information shared with the OAuth client. Default value is **profile email**.

Google scope
''''''''''''

This setting isn't available in the System Console and can only be set in ``config.json``.

+---------------------------------------------------------------+-------------------------------------------------------------+
| Standard setting for OAuth to determine the scope of | - System Config path: N/A |
| information shared with the OAuth client. | - ``config.json`` setting: ``GoogleSettings`` > ``Scope`` |
| | - Environment variable: ``MM_GOOGLESETTINGS_SCOPE`` |
| String input. Recommended setting is ``profile email``. | |
+---------------------------------------------------------------+-------------------------------------------------------------+

Entra ID OAuth 2.0 settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -2112,6 +2191,25 @@ Entra ID OAuth 2.0 Token endpoint
| String input. | - Environment variable: ``MM_OFFICE365SETTINGS_TOKENENDPOINT`` |
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------+

.. config:setting:: oauth-entra-id-scope
:displayname: Entra ID scope (OAuth - Entra ID)
:systemconsole: N/A
:configjson: .Office365Settings.Scope
:environment: MM_OFFICE365SETTINGS_SCOPE
:description: Standard setting for OAuth to determine the scope of information shared with the OAuth client. Recommended setting is **User.Read**.

Entra ID scope
''''''''''''''

This setting isn't available in the System Console and can only be set in ``config.json``.

+---------------------------------------------------------------+---------------------------------------------------------------+
| Standard setting for OAuth to determine the scope of | - System Config path: N/A |
| information shared with the OAuth client. | - ``config.json`` setting: ``Office365Settings`` > ``Scope`` |
| | - Environment variable: ``MM_OFFICE365SETTINGS_SCOPE`` |
| String input. Recommended setting is ``User.Read``. | |
+---------------------------------------------------------------+---------------------------------------------------------------+

----

OpenID Connect
Expand Down
62 changes: 62 additions & 0 deletions source/administration-guide/configure/compliance-configuration-settings.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -297,6 +297,25 @@ The SMTP server port that will receive your Global Relay EML file when a `custom
| This feature's ``config.json`` setting is ``".MessageExportSettings.GlobalRelaySettings.CustomSMTPPort": "25"`` with string input. |
+------------------------------------------------------------------------------------------------------------------------------------+

.. config:setting:: global-relay-smtp-server-timeout
:displayname: Global Relay SMTP server timeout (Compliance Export - Global Relay EML)
:systemconsole: N/A
:configjson: .MessageExportSettings.GlobalRelaySettings.SMTPServerTimeout
:environment: MM_MESSAGEEXPORTSETTINGS_GLOBALRELAYSETTINGS_SMTPSERVERTIMEOUT
:description: The number of seconds that can elapse before the connection attempt to the SMTP server is abandoned. Default is **1800** seconds.

Global Relay SMTP server timeout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This setting isn't available in the System Console and can only be set in ``config.json``.

+---------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| The number of seconds that can elapse before the connection | - System Config path: N/A |
| attempt to the SMTP server is abandoned. | - ``config.json`` setting: ``MessageExportSettings.GlobalRelaySettings.SMTPServerTimeout`` > ``1800`` |
| | - Environment variable: ``MM_MESSAGEEXPORTSETTINGS_GLOBALRELAYSETTINGS_SMTPSERVERTIMEOUT`` |
| Numeric value. Default is **1800** seconds. | |
+---------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+

.. config:setting:: message-export-batch-size
:displayname: Message export batch size (Compliance Export)
:systemconsole: N/A
Expand All @@ -315,6 +334,49 @@ Determines how many new posts are batched together to a compliance export file.
| This feature's ``config.json`` setting is ``"BatchSize": 10000`` with numerical input. |
+---------------------------------------------------------------------------------------------+

.. config:setting:: export-from-timestamp
:displayname: Export from timestamp (Compliance Export)
:systemconsole: N/A
:configjson: .MessageExportSettings.ExportFromTimestamp
:environment: MM_MESSAGEEXPORTSETTINGS_EXPORTFROMTIMESTAMP
:description: Set the Unix timestamp (seconds since epoch, UTC) to export data from. Default is **0**.

Export from timestamp
~~~~~~~~~~~~~~~~~~~~~

.. include:: ../../_static/badges/ent-plus.rst
:start-after: :nosearch:

This setting isn't available in the System Console and can only be set in ``config.json``.

+---------------------------------------------------------------+--------------------------------------------------------------------------------------------+
| Set the Unix timestamp (seconds since epoch, UTC) to export | - System Config path: N/A |
| data from. | - ``config.json`` setting: ``MessageExportSettings.ExportFromTimestamp`` > ``0`` |
| | - Environment variable: ``MM_MESSAGEEXPORTSETTINGS_EXPORTFROMTIMESTAMP`` |
| Numeric value. Default is **0**. | |
+---------------------------------------------------------------+--------------------------------------------------------------------------------------------+

.. config:setting:: file-location
:displayname: File location (Compliance Export)
:systemconsole: N/A
:configjson: FileLocation
:environment: N/A
:description: Set the file location of the compliance exports. Default value is **export**.

File location
~~~~~~~~~~~~~

.. include:: ../../_static/badges/ent-plus.rst
:start-after: :nosearch:

This setting isn't available in the System Console and can only be set in ``config.json``.

Set the file location of the compliance exports. By default, they are written to the ``exports`` subdirectory of the configured :ref:`Local Storage directory <administration-guide/configure/environment-configuration-settings:local storage directory>`.

+-------------------------------------------------------------------------------------------+
| This feature's ``config.json`` setting is ``"FileLocation": "export"`` with string input. |
Comment on lines +374 to +377
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

export vs exports path wording is inconsistent.

Line 374 says the default writes to the exports subdirectory, but Line 377 documents the default config value as "FileLocation": "export". Please align these values to avoid admin misconfiguration.

Based on learnings, “Describe Mattermost feature behavior, UI labels, and capability boundaries accurately.”

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@source/administration-guide/configure/compliance-configuration-settings.rst`
around lines 374 - 377, The documentation is inconsistent: the paragraph claims
exports are written to the "exports" subdirectory but the example config shows
"FileLocation": "export"; update one to match the other. Locate the text that
mentions the default directory ("exports" subdirectory) and the config example
showing "FileLocation": "export" and make them consistent (either change the
config example to "FileLocation": "exports" or change the paragraph to refer to
"export"), ensuring the displayed config value and the prose use the exact same
string.

+-------------------------------------------------------------------------------------------+

Run compliance export job now
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down
54 changes: 47 additions & 7 deletions source/administration-guide/configure/deprecated-configuration-settings.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,30 +32,54 @@ Bleve settings

*Bleve search has been deprecated from Mattermost v11.0. We recommend using Elasticsearch or OpenSearch for enterprise search capabilities.*

.. config:setting:: enable-bleve-indexing
:displayname: Enable Bleve indexing (Deprecated)
:systemconsole: N/A
:configjson: EnableIndexing
:environment: N/A

- **true**: The indexing of new posts occurs automatically.
- **false**: **(Default)** The indexing of new posts does not occur automatically.

Enable Bleve indexing
~~~~~~~~~~~~~~~~~~~~~

*Deprecated from Mattermost v11.0*
*Deprecated in Mattermost v11.0*

This setting was available in the System Console by going to **Experimental > Bleve**, or by editing the ``config.json`` file.

Bleve search was deprecated in favor of database search and Elasticsearch. Use database search (default) or configure Elasticsearch for large deployments.

**True**: The indexing of new posts occurs automatically.

**False**: The indexing of new posts does not occur automatically.

This setting is no longer functional.

+------------------------------------------------------------------------------------------------------------+
| This feature's ``config.json`` setting is ``"EnableIndexing": false`` with options ``true`` and ``false``. |
+------------------------------------------------------------------------------------------------------------+

.. config:setting:: index-directory
:displayname: Index directory (Deprecated)
:systemconsole: N/A
:configjson: IndexDir
:environment: N/A
:description: Directory path to use for storing bleve indexes.

Index directory
~~~~~~~~~~~~~~~

*Deprecated from Mattermost v11.0*
*Deprecated in Mattermost v11.0*

This setting was available in the System Console by going to **Experimental > Bleve**, or by editing the ``config.json`` file.

Bleve search was deprecated in favor of database search and Elasticsearch. Use database search (default) or configure Elasticsearch for large deployments.

Directory path to use for storing bleve indexes.

This setting is no longer functional.

+-----------------------------------------------------------------------------------------------------------+
| This feature's ``config.json`` setting is ``"IndexDir": ""`` with string input. |
+-----------------------------------------------------------------------------------------------------------+
Expand All @@ -71,41 +95,57 @@ Purge indexes
Select **Purge Index** to remove the contents of the Bleve index directory. Search results may be incomplete until a bulk index of the existing database is rebuilt.

.. config:setting:: enable-bleve-indexingsearch
:displayname: Enable Bleve for search queries (Experimental)
:systemconsole: Experimental > Bleve
:displayname: Enable Bleve for search queries (Deprecated)
:systemconsole: N/A
:configjson: EnableSearching
:environment: N/A

- **true**: Search queries will use bleve search.
- **false**: **(Default)** Search queries will not use bleve search.


Enable Bleve for search queries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*Deprecated from Mattermost v11.0*
*Deprecated in Mattermost v11.0*

This setting was available in the System Console by going to **Experimental > Bleve**, or by editing the ``config.json`` file.

Bleve search was deprecated in favor of database search and Elasticsearch. Use database search (default) or configure Elasticsearch for large deployments.

**True**: Search queries will use bleve search.

**False**: Search queries will not use bleve search.

This setting is no longer functional.

+--------------------------------------------------------------------------------------------------------------+
| This feature's ``config.json`` setting is ``"EnableSearching": false`` with options ``true`` and ``false``. |
+--------------------------------------------------------------------------------------------------------------+

.. config:setting:: enable-bleve-indexingautocomplete
:displayname: Enable Bleve for autocomplete queries (Deprecated)
:systemconsole: N/A
:configjson: EnableAutocomplete
:environment: N/A

- **true**: Autocomplete queries will use bleve search.
- **false**: **(Default)** Autocomplete queries will not use bleve search.

Enable Bleve for autocomplete queries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*Deprecated from Mattermost v11.0*
*Deprecated in Mattermost v11.0*

This setting was available in the System Console by going to **Experimental > Bleve**, or by editing the ``config.json`` file.

Bleve search was deprecated in favor of database search and Elasticsearch. Use database search (default) or configure Elasticsearch for large deployments.

**True**: Autocomplete queries will use bleve search.

**False**: Autocomplete queries will not use bleve search.

This setting is no longer functional.

+-----------------------------------------------------------------------------------------------------------------+
| This feature's ``config.json`` setting is ``"EnableAutocomplete": false`` with options ``true`` and ``false``. |
+-----------------------------------------------------------------------------------------------------------------+
Expand Down
Loading