Skip to main content

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.

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.

Create an Entra Application​

  • Open Entra admin center > Identity > Applications > App registrations
  • 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
    • RoleManagement.Read.All
    • Policy.Read.ConditionalAccess
    • UserAuthenticationMethod.Read.All
  • 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 - Uncomment the block below to fail the build if tests fail
#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

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