Sending reports

The built-in Maester Cloud Runner runs your tests for you over the Microsoft Graph connection from setup. You can also send reports yourself, from wherever your runs already happen, with the Send-MaesterCloudReport command.

Maester Cloud accepts two report families: Maester test results (the JSON produced by Invoke-Maester) and the Zero Trust Assessment report.

Who can upload

Uploads are authenticated with Entra tokens from the tenant your portal signs in with, and nobody can upload until an Owner allows them on the portal's Access page. That includes Owners themselves: Uploader is a separate permission from Reader, Admin, and Owner, and it starts off for everyone.

Send-MaesterCloudReport ships in the MaesterCloud module on the PowerShell Gallery. It needs PowerShell 7.2 or later, plus the Microsoft.Graph.Authentication module for signing in as a person, or the Azure CLI for automation.

Upload as yourself

1. Sign in to the portal once, so you appear on the Access page.
2. An Owner opens Access and ticks Uploader next to your name under Users. If you are the Owner, tick it for yourself.
3. Install the module: Install-Module MaesterCloud -Scope CurrentUser
4. Check your access. A browser prompt opens; pick the account you use for the portal. Nothing is uploaded.

   Test-MaesterCloudUpload -PortalUrl "https://your-portal-url" -AuthenticationMode Delegated

5. When every check passes, send a report with the command below. In the same PowerShell session, you won't be asked to sign in again.

Upload from automation

1. Pick the identity the pipeline runs as, in the portal's tenant: an app registration (for GitHub Actions, give it a federated credential for your repository) or a managed identity (for Azure Automation or an Azure VM).
2. Find its two IDs:
   • Application (client) ID: on the app registration's Overview, or the managed identity's Client ID.
   • Service principal object ID: the Object ID under Enterprise applications, or the managed identity's Object (principal) ID. It is not the Object ID on the App registration page, and using that one is the most common reason uploads are refused.
3. As an Owner, open Access and, under Automation uploaders, search for the app by name in Find the app, or paste its client ID or either object ID. Picking it fills in both IDs; each result links to the app in Entra so you can check it is the right one. Then select Add uploader. You can also type both IDs yourself: when the portal's tenant has a verified Microsoft Graph connection, the portal checks the object ID and replaces an App registration Object ID with the right one for you. Search needs that connection too.
4. Select the new uploader and run the Grant Default Access PowerShell the page shows, once, as an Entra administrator. It assigns the identity to the portal's enterprise application, which is required when that application has Assignment required turned on.
5. Sign the pipeline in to the Azure CLI as that identity: azure/login in GitHub Actions, az login --service-principal, or az login --identity for a managed identity.
6. Check its access, then send with -AuthenticationMode AppOnly:

   Test-MaesterCloudUpload -PortalUrl "https://your-portal-url" -AuthenticationMode AppOnly

Check your access

Test-MaesterCloudUpload signs in the same way Send-MaesterCloudReport does, reports each step, and uploads nothing. A failed step says what to change.

Add -Quiet to get only $true or $false, for example to fail a pipeline before it runs Maester.

Common problems

The command

The portal's Get started page shows this command with your portal URL filled in.

Send-MaesterCloudReport `
  -PortalUrl "https://your-portal-url" `
  -JsonPath ./TestResults.json `
  -HtmlPath ./TestResults.html `
  -Source "Manual upload" `
  -AuthenticationMode Delegated

• -PortalUrl is your Maester Cloud portal. The command reads the tenant, client ID, and scopes it needs from the portal, so there is nothing else to configure.
• -JsonPath is required. -HtmlPath is optional but recommended, because the original HTML report is stored and viewable from the portal.
• -AuthenticationMode is Delegated for a person, who signs in through a browser prompt, or AppOnly for automation signed in to the Azure CLI as a service principal or managed identity. The default, Auto, tries app-only first and then delegated.
• -Source is a free-text label ("GitHub Actions", "Azure Automation") shown on every run for provenance.

If a machine can't reach the PowerShell Gallery, your portal also serves the same commands: download /scripts/MaesterCloudReport.ps1 and /scripts/MaesterCloudUploader.psm1 from your portal URL into one folder, then Import-Module ./MaesterCloudUploader.psm1.

Use your portal's test configuration

The built-in runner applies what you set on the portal's Configuration page automatically. When you run Maester yourself, call Get-MaesterCloudConfig before Invoke-Maester so your run matches: it writes the tenant's emergency access accounts into Custom/maester-config.json in your tests folder, and returns the tests turned off (or awaiting review) for that tenant to pass to -ExcludeTag.

$config = Get-MaesterCloudConfig `
  -PortalUrl "https://your-portal-url" `
  -TenantId $tenantId `
  -Path ./tests `
  -AuthenticationMode AppOnly

Invoke-Maester -Path ./tests -ExcludeTag $config.ExcludeTag

Not every Maester test carries its id as a tag, so your portal also drops turned-off tests when the report arrives: a test you turned off never lands in your history either way.

What happens after you send

1. Upload-init: your portal validates the token (issuer, audience, and tenant must match your deployment, and the caller must be an allowed uploader) and opens a new run.
2. Artifacts upload: the JSON (and HTML) are sent through the same authenticated API into your deployment's private storage. The run is only marked complete after every file has arrived, so processing never starts on a half-uploaded report.
3. Processing: your deployment identifies the report family, confirms the assessed tenant, and parses every test into a stored result: id, title, outcome, severity, block, tags, and the Microsoft product it belongs to. Tests turned off for that tenant, or new and awaiting review, are left out. Transient failures retry automatically.
4. Recording: the run appears in the portal with pass/fail/skip counts; the raw files stay downloadable as evidence; the run is diffed against your previous one; and, if you've set them up, drift emails go out.

Run it on a schedule

Drift is only as fresh as your runs. If you don't use the built-in runner, schedule a daily run (a GitHub Actions workflow, an Azure DevOps pipeline, or Azure Automation) ending with Send-MaesterCloudReport -AuthenticationMode AppOnly. Real PowerShell-written files (including UTF-8 BOMs) are handled as-is; no massaging needed.

In GitHub Actions, sign in with a federated credential on the uploader's app registration, so the workflow stores no secret:

permissions:
  id-token: write
  contents: read

steps:
  # ... run Maester so ./TestResults.json exists ...

  - uses: azure/login@v2
    with:
      tenant-id: ${{ vars.MAESTER_CLOUD_TENANT_ID }}
      client-id: ${{ vars.MAESTER_CLOUD_UPLOADER_CLIENT_ID }}
      allow-no-subscriptions: true

  - name: Send to Maester Cloud
    shell: pwsh
    run: |
      Install-Module MaesterCloud -Scope CurrentUser -Force
      Send-MaesterCloudReport `
        -PortalUrl "https://your-portal-url" `
        -JsonPath ./TestResults.json `
        -HtmlPath ./TestResults.html `
        -Source "GitHub Actions" `
        -AuthenticationMode AppOnly

Statuses you'll see