Maester 🔥 Github Action

Monitor your Microsoft 365 tenant's security configuration using Maester, the PowerShell-based test automation framework.

Check out the Maester documentation for more information on how to use Maester, or the github action documentation for more details on how to use the action.

• Run public and private tests for Microsoft 365 security configurations.
• Supports Exchange Online and Teams tests.
• Customizable test runs with include/exclude tags.
• Detailed test results with optional email and Teams notifications.
• Uploads test results as GitHub Action artifacts.
• Supports telemetry control for privacy-conscious workflows.

Here’s an example of how to use the Maester Action in your workflow file .github/workflows/maester.yml:

name: Run Maester Tests

on:
  push:
    branches:
      - main

  schedule:
    # Daily at 7:30 UTC, change accordingly
    - cron: "30 7 * * *"

  # Allows to run this workflow manually from the Actions tab
  workflow_dispatch:

permissions:
      id-token: write
      contents: read
      checks: write

jobs:
  test:
    name: Run Maester Test Job
    runs-on: ubuntu-latest

    steps:
      - name: Run Maester 🔥
        id: maester
        # Set the action version to a specific version, to keep using that exact version.
        # Or even better set it to a specific commit SHA to be sure nothing breaks unexpectedly.
        uses: maester365/maester-action@main
        with:
          tenant_id: ${{ secrets.AZURE_TENANT_ID }}
          client_id: ${{ secrets.AZURE_CLIENT_ID }}
          include_public_tests: true
          include_private_tests: false
          include_exchange: false
          include_teams: false
          # Set a specific version of the powershell module here or 'latest' or 'preview'
          # check out https://www.powershellgallery.com/packages/Maester/
          maester_version: latest
          disable_telemetry: false
          step_summary: Table  # Full, Summary, Table, or false
          artifact_upload_html: true # Upload html report as separate artifact

      - name: Write status 📃
        shell: bash
        run: |
          echo "The result of the test run is: ${{ steps.maester.outputs.result }}"
          echo "Total tests: ${{ steps.maester.outputs.tests_total }}"
          echo "Passed tests: ${{ steps.maester.outputs.tests_passed }}"
          echo "Failed tests: ${{ steps.maester.outputs.tests_failed }}"
          echo "Skipped tests: ${{ steps.maester.outputs.tests_skipped }}"

Maester 3.0 runs the built-in tests from inside the module and no longer depends on Pester. This action keeps running Maester 2.x until you opt in: maester_version: latest and preview resolve to the newest 2.x release while maester_major_version is 2 (the default), even after 3.0 is published. Nothing changes until you set maester_major_version: "3".

On Maester 3 your repository only needs the workflow file. You no longer need a copy of maester-tests or Install-MaesterTests: the built-in tests ship in the module. Add a maester-config.json or a custom/ folder only if you want them.

Before:

      - name: Run Maester 🔥
        uses: maester365/maester-action@main
        with:
          tenant_id: ${{ secrets.AZURE_TENANT_ID }}
          client_id: ${{ secrets.AZURE_CLIENT_ID }}
          include_public_tests: true
          maester_version: latest

After:

      - name: Run Maester 🔥
        uses: maester365/maester-action@main
        with:
          tenant_id: ${{ secrets.AZURE_TENANT_ID }}
          client_id: ${{ secrets.AZURE_CLIENT_ID }}
          maester_major_version: "3"  # opt in to Maester 3.x
          maester_version: latest     # newest 3.x release (or 'preview', or an exact 3.x version)
          # The repository only holds this workflow file, so there is nothing to check out.
          # Leave this out (default 'true') if the repository has a maester-config.json or custom tests.
          include_private_tests: false

What changes on Maester 3:

• The built-in tests always run. The action no longer installs the public tests (maester365/maester-tests) into the workspace, so include_public_tests has no effect (you get a warning if you set it). Your repository needs only the workflow file, plus an optional maester-config.json and custom tests. With include_private_tests: false the repository is not checked out and Invoke-Maester runs without -Path. Set skip_builtin_tests: true to run only your custom tests (this needs include_private_tests: true), or use include_tags, test_ids and exclude_test_ids to pick tests.
• Custom Pester tests need Pester. Pester-format custom tests (*.Tests.ps1) need Pester 5.7.1 or later. The action installs it automatically when it finds *.Tests.ps1 files in the repository; set install_pester: true to always install it.
• The All and Full tags were removed. The action stops with an error if include_tags or exclude_tags contain them. Use include_preview_tests instead of All and include_longrunning_tests instead of Full.
• PowerShell 7.4 or later is required. GitHub-hosted runners already have it; check self-hosted runners.
• New inputs: skip_builtin_tests, install_pester, test_ids, exclude_test_ids and config_path. They only work on Maester 3; the action fails if you set them while maester_major_version is 2.
• An exact maester_version must match maester_major_version: maester_version: 3.0.0 with maester_major_version: "2" fails with an error instead of guessing. Exact 1.x versions still work with maester_major_version: "2".

Read Upgrading from Maester 2.x before you switch, and try the upgrade on a branch or with workflow_dispatch first.

We welcome contributions, since this is a community project! Please check out our contributing guidelines for more information on how to get started.

Thanks for using Maester! If you have any questions or feedback, feel free to reach out to us on GitHub Discussions or Discord.