Fix incorrect JSON example for mmctl user migrate-auth (email → SAML)

[ewwollesen]

Summary

The mmctl user migrate-auth docs page contained two conflicting JSON examples for the SAML users file. This removes the inaccurate one.

The "user.json Example" block showed an array of objects with auth_data / idp_id / saml_user_id keys. mmctl does not understand that format. In server/cmd/mmctl/commands/user.go, migrateAuthToSamlCmdF reads the users file straight into a Go map[string]string:

matches := map[string]string{}
if !auto {
    matchesFile := userArgs[2]
    file, err := os.ReadFile(matchesFile)
    ...
    if err := json.Unmarshal(file, &matches); err != nil {
        return fmt.Errorf("invalid json: %w", err)
    }
}

Feeding it the array form fails with invalid json (cannot unmarshal an array into a map). The keys auth_data / idp_id / saml_user_id appear nowhere in the migrate-auth code path.

The correct format — a flat object mapping each Mattermost email to its SAML username — is already documented immediately above, under migration-options (saml) → users_file:

{
   "usr1@email.com": "usr.one",
   "usr2@email.com": "usr.two"
}

So this PR simply deletes the misleading second example, leaving the accurate one in place.

Test plan

• Confirmed against mmctl source (server/cmd/mmctl/commands/user.go, migrateAuthToSamlCmdF) that the users file is unmarshalled into map[string]string.
• Verified auth_data / idp_id / saml_user_id are not referenced anywhere in the mmctl migrate-auth path.
• gmake clean html builds successfully (exit 0). Build reports 26 warnings, all in unrelated files (Azure deploy guide, upgrade notes, autotranslation, generated agents docs, etc.) and pre-existing; zero reference mmctl-command-line-tool.rst. This change is a pure deletion and introduces no new warnings.

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

A duplicated "user.json Example" section (containing a JSON array block) under the mmctl user migrate-auth command in the mmctl documentation has been removed. The documentation now proceeds directly from the command usage example to the "Options" section.

Changes

mmctl user migrate-auth Docs Cleanup

Layer / File(s)	Summary
Remove duplicate user.json example block source/administration-guide/manage/mmctl-command-line-tool.rst	Deletes the 25-line "user.json Example" section (JSON array block) that was duplicated under mmctl user migrate-auth before the "Options" section.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: removing an incorrect JSON example from mmctl user migrate-auth documentation and specifying the correct format (email → SAML).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The pull request description is directly related to the changeset, providing clear rationale for removing an inaccurate JSON example from the mmctl documentation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/fix-mmctl-migrate-auth-saml-json-example

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Removes a misleading JSON example from the mmctl user migrate-auth documentation so the page only presents the map[email]saml_username format that mmctl actually accepts for SAML migrations.

Changes:

• Deleted the incorrect user.json Example block that showed an array/object structure unsupported by mmctl user migrate-auth email saml.
• Leaves the existing, correct users_file JSON mapping example in place.

[github-actions]

Newest code from mattermost has been published to preview environment for Git SHA 07adeb2

[ewwollesen]

@hanzei Would you mind taking a look at this, please? It's just a simple docs change, but I want to make sure that I (and Claude) have read the code correctly that block isn't actually needed.