Set up Maester in GitHub

This guide will walk you through setting up Maester in GitHub and automate the running of tests using GitHub Actions.

Why GitHub?

GitHub is the quickest and easiest way to get started with automating Maester. The free tier includes 2,000 minutes per month for private repositories which is more than enough to run your Maester tests daily.

Set up your Maester tests repository in GitHub

Pre-requisites

If you are new to GitHub, create an account at github.com

Create a new repository and import the Maester Tests repository

Open https://github.com/new/import
Fill in the following fields:
- Your old repository’s clone URL: https://github.com/maester365/maester-tests
- Repository name: E.g. maester-tests
- Private: Select this option to keep your tests private
Select Begin Import

Set up the GitHub Actions workflow

There are many ways to authenticate with Microsoft Entra from GitHub Actions. We recommend using workload identity federation as it is more secure, requires less maintenance and is the easiest to set up.

If you’re unable to use more advanced options like certificates stored in Azure Key Vault, which need an Azure subscription, there’s also guidance available for using client secrets.

Workload identity federation (recommended) uses OpenID Connect (OIDC) to authenticate with Microsoft Entra protected resources without using secrets.
Client secret uses a secret to authenticate with Microsoft Entra protected resources.

Workload identity federation (recommended)
Client secret

This guide is based on Use GitHub Actions to connect to Azure

Pre-requisites

An Azure subscription is required for this method. This Azure subscription is required to set up workload identity federation authentication. No Azure resources will be created and there are no costs associated with it.
- If you don't have an Azure subscription, you can create one by following Create a Microsoft Customer Agreement subscription or ask your Azure administrator to create one.

Create an Entra Application

Open Entra admin center > Identity > Applications > App registrations
- Tip: enappreg.cmd.ms is a shortcut to the App registrations page.
Select New registration
Enter a name for the application (e.g. Maester DevOps Account)
Select Register

Grant permissions to Microsoft Graph

Open the application you created in the previous step
Select API permissions > Add a permission
Select Microsoft Graph > Application permissions
Search for each of the permissions and check the box next to each permission:
- Directory.Read.All
- Policy.Read.All
- Reports.Read.All
- DirectoryRecommendations.Read.All
- PrivilegedAccess.Read.AzureAD
- IdentityRiskEvent.Read.All
- RoleEligibilitySchedule.Read.Directory
Select Add permissions
Select Grant admin consent for [your organization]
Select Yes to confirm

Add federated credentials

Select Certificates & secrets
Select Federated credentials, select Add credential
For Federated credential scenario, select GitHub Actions deploying Azure resources
Fill in the following fields
- Organization: Your GitHub organization name or GitHub username. E.g. jasonf
- Repository: Your GitHub repository name (from the previous step). E.g. maester-tests
- Entity type: Branch
- GitHub branch name: main
- Credential details > Name: E.g. maester-devops
Select Add

Create GitHub secrets

Open your maester-tests GitHub repository and go to Settings
Select Security > Secrets and variables > Actions
Add the secrets listed below by selecting New repository secret
To look up these values you will need to use the Entra portal, open the application you created earlier and copy the following values from the Overview page:
- Name: AZURE_TENANT_ID, Value: The Directory (tenant) ID of the Entra tenant
- Name: AZURE_CLIENT_ID, Value: The Application (client) ID of the Entra application you created
Save each secret by selecting Add secret.

Enable GitHub Actions

Open your maester-tests GitHub repository and go to Settings
Select Actions > General > Actions permissions
Select Allow all actions
Select Save

Create GitHub Action worklow for Maester

Open your maester-tests GitHub repository and go to Actions
Select Skip this and set up a workflow yourself
Copy and paste the code below into the editor
Select Commit changes... to save the workflow
Select Actions > maester-daily-tests to view the status of the pipeline

name: Maester Daily Tests

on:
  push:
    branches: ["main"]
  # Run once a day at midnight
  schedule:
    - cron: "0 0 * * *"
  # Allows to run this workflow manually from the Actions tab
  workflow_dispatch:

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

jobs:
  run-maester-tests:
    name: Run Maester Tests
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set current date as env variable
      run: echo "NOW=$(date +'%Y-%m-%d-T%H%M%S')" >> $GITHUB_ENV
    - name: 'Az CLI login'
      uses: azure/login@v2
      with:
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          allow-no-subscriptions: true
    - 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

          # Install Maester
          Install-Module Maester -Force

          # Configure test results
          $PesterConfiguration = New-PesterConfiguration
          $PesterConfiguration.Output.Verbosity = 'None'

          # Run Maester tests
          $results = Invoke-Maester -Path tests/Maester/ -PesterConfiguration $PesterConfiguration -OutputFolder test-results -OutputFolderFileName "test-results" -PassThru

          # Add step summary
          $summary = Get-Content test-results/test-results.md
          Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value $summary

          # Flag status to GitHub
          if ($results.Result -ne 'Passed'){
            Write-Error "Status = $($results.Result): See Maester Test Report below for details."
          }
        azPSVersion: "latest"

    - name: Archive Maester Html Report
      uses: actions/upload-artifact@v4
      if: always()
      with:
        name: maester-test-results-${{ env.NOW }}
        path: test-results

Create an Entra Application

Open Entra admin center > Identity > Applications > App registrations
- Tip: enappreg.cmd.ms is a shortcut to the App registrations page.
Select New registration
Enter a name for the application (e.g. Maester DevOps Account)
Select Register

Grant permissions to Microsoft Graph

Open the application you created in the previous step
Select API permissions > Add a permission
Select Microsoft Graph > Application permissions
Search for each of the permissions and check the box next to each permission:
- Directory.Read.All
- Policy.Read.All
- Reports.Read.All
- DirectoryRecommendations.Read.All
- PrivilegedAccess.Read.AzureAD
- IdentityRiskEvent.Read.All
- RoleEligibilitySchedule.Read.Directory
Select Add permissions
Select Grant admin consent for [your organization]
Select Yes to confirm

Create a client secret

Select Certificates & secrets > Client secrets > New client secret
Enter a description for the secret (e.g. Maester DevOps Secret)
Select Add
Copy the value of the secret, we will use this value in the Azure Pipeline

Create GitHub secrets

Open your maester-tests GitHub repository and go to Settings
Select Security > Secrets and variables > Actions
Add the three secrets listed below by selecting New repository secret
To look up these values you will need to use the Entra portal, open the application you created earlier and copy the following values from the Overview page:
- Name: AZURE_TENANT_ID, Value: The Directory (tenant) ID of the Entra tenant
- Name: AZURE_CLIENT_ID, Value: The Application (client) ID of the Entra application you created
- Name: AZURE_CLIENT_SECRET, Value: The client secret you copied in the previous step
Save each secret by selecting Add secret.

Enable GitHub Actions

Open your maester-tests GitHub repository and go to Settings
Select Actions > General > Actions permissions
Select Allow all actions
Select Save

Create GitHub Action worklow for Maester

Open your maester-tests GitHub repository and go to Actions
Select Skip this and set up a workflow yourself
Copy and paste the code below into the editor
Select Commit changes... to save the workflow
Select Actions > maester-daily-tests to view the status of the pipeline

name: Maester Daily Tests

on:
  push:
    branches: ["main"]
  # Run once a day at midnight
  schedule:
    - cron: "0 0 * * *"
  # Allows to run this workflow manually from the Actions tab
  workflow_dispatch:

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

jobs:
  run-maester-tests:
    name: Run Maester Tests
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set current date as env variable
      run: echo "NOW=$(date +'%Y-%m-%d-T%H%M%S')" >> $GITHUB_ENV
    - name: Run Maester
      shell: pwsh
      env:
        TENANTID: ${{ secrets.AZURE_TENANT_ID }}
        CLIENTID: ${{ secrets.AZURE_CLIENT_ID }}
        CLIENTSECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
      run: |
        # Connect to Microsoft Graph
        $clientSecret = ConvertTo-SecureString -AsPlainText $env:CLIENTSECRET -Force
        [pscredential]$clientSecretCredential = New-Object System.Management.Automation.PSCredential($env:CLIENTID, $clientSecret)
        Connect-MgGraph -TenantId $env:TENANTID -ClientSecretCredential $clientSecretCredential

        # Install Maester
        Install-Module Maester -Force

        # Configure test results
        $PesterConfiguration = New-PesterConfiguration
        $PesterConfiguration.Output.Verbosity = 'None'

        # Run Maester tests
        $results = Invoke-Maester -Path tests/Maester/ -PesterConfiguration $PesterConfiguration -OutputFolder test-results -OutputFolderFileName "test-results" -PassThru

        # Add step summary
        $summary = Get-Content test-results/test-results.md
        Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value $summary

        # Flag status to GitHub
        if ($results.Result -ne 'Passed'){
          Write-Error "Status = $($results.Result): See Maester Test Report below for details."
        }

    - name: Archive Maester Html Report
      uses: actions/upload-artifact@v4
      if: always()
      with:
        name: maester-test-results-${{ env.NOW }}
        path: test-results

Manually running the Maester tests

To manually run the Maester tests workflow

Open your maester-tests GitHub repository and go to Actions
Select Maester Daily Tests from the left pane
Select Run workflow drop-down from the right pane
Select Run workflow button to start the workflow
Select the running workflow to view the status

Viewing test results

Open your maester-tests GitHub repository and go to Actions
Select a workflow run to view the results e.g. Maester Daily Tests

Summary view

The summary view shows the status of the workflow run, the duration, and the number of tests that passed, failed, and were skipped.

Screenshot of GitHub worklflow run summary Page

Maester report

The detailed Maester report can be downloaded by selecting the maester-test-results... file from the Artifacts section and opening the test-results.html page.

Screenshot of the downloaded Maester report

Summary Maester report

A detailed summary of the Maester report can be viewed by scrolling down Summary page.

Screenshot of Maester report in the GitHub Summary Page

Logs view

Select the Run Maester Tests job from Jobs in the left pane to view the raw logs.

Screenshot of GitHub workflow logs page

Keeping your Maester tests up to date

The Maester team will add new tests over time. To get the latest updates, use the commands below to update your GitHub repository with the latest tests.

Clone your fork of the maester-tests repository to your local computer. See Cloning a repository.
Update the Maester PowerShell module to the latest version and load it.
Change to the maester-tests\tests directory.
Run Update-MaesterTests.

cd maester-tests\tests

Update-Module Maester -Force
Import-Module Maester
Update-MaesterTests

Set up Maester in GitHub

Why GitHub?​

Set up your Maester tests repository in GitHub​

Pre-requisites​

Create a new repository and import the Maester Tests repository​

Set up the GitHub Actions workflow​

Pre-requisites​

Create an Entra Application​

Grant permissions to Microsoft Graph​

Add federated credentials​

Create GitHub secrets​

Enable GitHub Actions​

Create GitHub Action worklow for Maester​

Create an Entra Application​

Grant permissions to Microsoft Graph​

Create a client secret​

Create GitHub secrets​

Enable GitHub Actions​

Create GitHub Action worklow for Maester​

Manually running the Maester tests​

Viewing test results​

Summary view​

Maester report​

Summary Maester report​

Logs view​

Keeping your Maester tests up to date​

Why GitHub?

Set up your Maester tests repository in GitHub

Pre-requisites

Create a new repository and import the Maester Tests repository

Set up the GitHub Actions workflow

Pre-requisites

Create an Entra Application

Grant permissions to Microsoft Graph

Add federated credentials

Create GitHub secrets

Enable GitHub Actions

Create GitHub Action worklow for Maester

Create an Entra Application

Grant permissions to Microsoft Graph

Create a client secret

Create GitHub secrets

Enable GitHub Actions

Create GitHub Action worklow for Maester

Manually running the Maester tests

Viewing test results

Summary view

Maester report

Summary Maester report

Logs view

Keeping your Maester tests up to date