30-second answer

PowerShell
m365-governance diff ./march.json ./august.json --format markdown

Both arguments are assessments, from assess. A report cannot be compared, because it does not carry what it was decided from.

The distinction the comparison exists to make

A rule that read pass in March and fail in August has two explanations, and they call for opposite responses:

  • the tenant changed. Somebody turned something on. That is a finding, and somebody should look at it.
  • the rule changed. A newer engine tightened what the rule establishes. The tenant may be untouched, and there is nothing to fix.

A comparison that reported only outcomes would present the second as the first, and a team would spend a morning looking for a change nobody made. The engine records which rules moved version, and the comparison keeps them apart.

In a pipeline

PowerShell
m365-governance diff ./before.json ./after.json --fail-on-regression

Exits non-zero when any rule left pass. That is the setting for a build that treats losing a pass as a failure, and it says nothing about rules that were already failing.

What it does not say

That the estate improved. A comparison is between two documents; if the second collection saw less than the first, findings can disappear because nobody looked rather than because anything was fixed. Coverage travels with each assessment for exactly that reason, and reading it is part of reading a comparison.

Where to go deeper