action.yml

name: "Maester Action"
description: "Monitor your Microsoft 365 tenant's security configuration using Maester THE PowerShell-based test automation framework"
branding:
  icon: "check-circle"
  color: "red"
inputs:
  tenant_id:
    description: "Entra ID Tenant ID"
    required: true
  client_id:
    description: "App Registration Client ID"
    required: true
  include_public_tests:
    description: "Include public test repository 'maester365/maester-tests' as well as private tests in the test run"
    required: false
    default: "true"
  mail_recipients:
    description: "A list of email addresses to send the test results to. Please separate multiple email addresses with a comma."
    required: false
    default: ""
  mail_userid:
    description: "The user id of the sender of the mail. This is required since the action is using application permissions."
    required: false
    default: ""
  mail_testresultsuri:
    description: "Uri to the detailed test results page."
    required: false
    default: "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
  include_tags:
    description: "A list of tags to include in the test run. Please separate multiple tags with a comma."
    required: false
    default: ""
  exclude_tags:
    description: "A list of tags to exclude from the test run. Please separate multiple tags with a comma."
    required: false
    default: ""
  pester_verbosity:
    description: "Pester verbosity level. Options: 'None', 'Normal', 'Detailed', 'Diagnostic'"
    required: false
    default: "None"
  step_summary:
    type: boolean
    description: "Define whether a summary is outputted to GitHub Actions."
    required: false
    default: true
  artifact_upload:
    type: boolean
    description: "Define whether the results are uploaded as Artifacts."
    required: false
    default: true

runs:
  using: "composite"
  steps:
    - name: Sign in to Entra ID
      uses: azure/login@v2
      with:
        client-id: ${{ inputs.client_id }}
        tenant-id: ${{ inputs.tenant_id }}
        allow-no-subscriptions: true

    - name: Set current date as env variable
      shell: bash
      run: echo "NOW=$(date +'%Y-%m-%d-T%H%M%S')" >> $GITHUB_ENV

    - name: Checkout latest public tests
      if: ${{ inputs.include_public_tests == 'true' }}
      uses: actions/checkout@v4
      with:
        repository: maester365/maester-tests
        path: public-tests

    - name: Checkout latest private tests
      uses: actions/checkout@v4
      with:
        path: private-tests

    - name: Run Maester
      uses: azure/powershell@v2
      with:
        inlineScript: |
          # Get Token
          $token = az account get-access-token --resource-type ms-graph

          # Connect to Microsoft Graph
          $accessToken = ($token | ConvertFrom-Json).accessToken | ConvertTo-SecureString -AsPlainText -Force
          Connect-MgGraph -AccessToken $accessToken -NoWelcome

          # Install Maester
          Install-Module Maester -Force

          # Configure test results
          $PesterConfiguration = New-PesterConfiguration
          $PesterConfiguration.Output.Verbosity = '${{ inputs.pester_verbosity }}'
          Write-Host "Pester verbosity level set to: $($PesterConfiguration.Output.Verbosity.Value)"

          $MaesterParameters = @{
              Path                 = '${{ github.workspace }}'
              PesterConfiguration  = $PesterConfiguration
              OutputFolder         = 'test-results'
              OutputFolderFileName = 'test-results'
              PassThru             = $true
          }

          # Check if test tags are provided
          if ( [string]::IsNullOrWhiteSpace( '${{ inputs.include_tags }}' ) -eq $false ) {
              $TestTags = '${{ inputs.include_tags }}' -split ','
              $MaesterParameters.Add( 'Tag', $TestTags )
              Write-Host "Running tests with tags: $TestTags"
          }

          # Check if exclude test tags are provided
          if ( [string]::IsNullOrWhiteSpace( '${{ inputs.exclude_tags }}' ) -eq $false ) {
              $ExcludeTestTags = '${{ inputs.exclude_tags }}' -split ','
              $MaesterParameters.Add( 'ExcludeTag', $ExcludeTestTags )
              Write-Host "Excluding tests with tags: $ExcludeTestTags"
          }

          # Check if mail recipients and mail userid are provided
          if ( [string]::IsNullOrWhiteSpace( '${{ inputs.mail_userid }}' ) -eq $false ) {
              if ( [string]::IsNullOrWhiteSpace( '${{ inputs.mail_recipients }}' ) -eq $false ) {
                  # Add mail parameters
                  $MaesterParameters.Add( 'MailUserId', '${{ inputs.mail_userid }}' )
                  $Recipients = '${{ inputs.mail_recipients }}' -split ','
                  $MaesterParameters.Add( 'MailRecipient', $Recipients )
                  $MaesterParameters.Add( 'MailTestResultsUri', '${{ inputs.mail_testresultsuri }}' )
                  Write-Host "Mail notification will be sent to: $Recipients"
              } else {
                  Write-Warning "Mail recipients are not provided. Skipping mail notification."
              }
          }

          # Run Maester tests
          $results = Invoke-Maester @MaesterParameters

          if('${{ inputs.step_summary }}' -ne $false) {
            # Add step summary
            $summary = Get-Content test-results/test-results.md
            Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value $summary
          }
        azPSVersion: "latest"

    - name: Archive Maester Html Report
      uses: actions/upload-artifact@v4
      if: ${{ inputs.artifact_upload == 'true' }}
      with:
        name: maester-test-results-${{ env.NOW }}
        path: test-results
        include-hidden-files: true