# Set up Maester in BitBucket
Source: https://maester.dev/docs/monitoring/bitbucket
# Set up Maester in BitBucket
This guide will walk you through setting up Maester in BitBucket and automate the running of tests using BitBucket Pipelines.
## Set up your Maester tests repository in BitBucket
### Pre-requisites
- If you are new to BitBucket, create an account at [BitBucket.com](https://www.atlassian.com/try/cloud/signup?bundle=bitbucket) for organizations
- If you use BitBucket.com, you can run your CI/CD pipelines workflows on [BitBucket-hosted runners](https://www.atlassian.com/software/bitbucket/features/pipelines).
### Create a blank new project to always use the latest available Maester tests
The built-in Maester tests ship inside the Maester PowerShell module, and the pipeline below installs the latest module on every run. The repository only holds the pipeline. Later, you can add a `maester-config.json` to change settings (see [Configuration](../configuration/overview.md)) and a `custom` folder for your own tests (see [Writing custom tests](../writing-tests/index.mdx)).
- On the top bar, at the top, select 'Create ' and select 'Repository' from the dropdown.
- Create a New Repository [Create a repository](https://support.atlassian.com/bitbucket-cloud/docs/create-a-repository/)
- Project: Choose an existing project or create a new one.
- Repository name: Give your repository a descriptive name (e.g., maester-monitoring).
- Select the checkbox Access Level: Private Repository
- Once the repository is created, navigate to the **Repository settings** --> **Settings** in left navigation bar. From **Settings** toggle **Enable Pipelines.**
- Click on the **Configure bitbucket-pipelines.yml.** and Click on the **Starter Pipeline** to create a pipeline. This will add the `bitbuckets-pipelines.yml` file for **Bitbucket CI/CD Pipeline**. We need to edit the initial code for running the Maester tests.
There are many ways to authenticate with Microsoft Entra. We currently have tested client secrets, but there are probably more options available.
- **Client secret** uses a secret to authenticate with Microsoft Entra protected resources.
:::caution
Client secret authentication is not recommended for long-term automation, and we recommend using workload identity federation when possible. Client secrets expire, require manual rotation and manual updates in your pipeline/repository variables.
:::
### Create Bitbucket repository variables
- Open your Maester Bitbucket repository and go to Repository settings.
- Select **Pipelines** > **Repository variables**.
- Add the three secrets listed below. Make sure to check the checkbox (`[x]`) for each variable.
- 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:
- Visibility: Visible, Key: **AZURE_TENANT_ID**, Value: The Directory (tenant) ID of the Entra tenant
- Visibility: Visible, Key: **AZURE_CLIENT_ID**, Value: The Application (client) ID of the Entra application you created
- Visibility: Masked and hidden, Key: **AZURE_CLIENT_SECRET**, Value: The client secret you copied in the previous step
- Save each secret by selecting **Add variable** at the bottom.
## Edit bitbucket-pipelines.yml file (using the pipeline editor or IDE)
```yaml
# Global options
options:
max-time: 120 # 2 hours max runtime for all pipelines
# Git clone behavior
clone:
depth: 1 # Shallow clone for faster checkout
# Cache and service container definitions
definitions:
caches:
powershell: ~/.powershell
# Docker image options (global)
image: mcr.microsoft.com/microsoftgraph/powershell:latest
# Pipeline configuration
pipelines:
custom:
run-maester-tests:
- stage:
name: Maester Testing Stage
# Step configuration
steps:
- step:
name: Run Maester Tests
size: 2x # Standard size
caches:
- powershell
script:
- mkdir test-results
- pwsh -c 'Write-host "Running in project $BITBUCKET_REPO_SLUG with results at $BITBUCKET_BUILD_NUMBER."'
- |
pwsh -Command '
# Connect to Microsoft Graph - Access environment variables correctly
$clientSecret = ConvertTo-SecureString -AsPlainText "$env:AZURE_CLIENT_SECRET" -Force
[pscredential] $clientSecretCredential = New-Object System.Management.Automation.PSCredential("$env:AZURE_CLIENT_ID", $clientSecret)
Connect-MgGraph -TenantId "$env:AZURE_TENANT_ID" -ClientSecretCredential $clientSecretCredential -NoWelcome
# Install Maester (the built-in tests ship inside the module)
Install-Module Maester -Force
# Path adds the custom tests and maester-config.json in this repository, if any
$MaesterParameters = @{
Path = "."
Verbosity = "None"
OutputFolder = "test-results"
OutputFolderFileName = "test-results"
PassThru = $true
NonInteractive = $true
}
# Add DisableTelemetry parameter
$MaesterParameters.Add("DisableTelemetry", $true)
Write-Host "Maester telemetry disabled: $($MaesterParameters.DisableTelemetry)"
# Run Maester tests
$results = Invoke-Maester @MaesterParameters
# View summary report
$results | Format-List Result, FailedCount, PassedCount, SkippedCount, TotalCount, TenantId, TenantName, CurrentVersion, LatestVersion
# Flag status to Bitbucket
if ($results.Result -ne "Passed") {
Write-Warning "Status = $($results.Result): see Maester Test Report for details."
exit 1
}
'
after-script:
- pwsh -c 'Write-host "Report can be opened in artifacts - test-results/test-results.html."'
artifacts:
- test-results/**
```
:::note
Maester 3.0 requires PowerShell 7.4 or later, which the `mcr.microsoft.com/microsoftgraph/powershell` image provides. Pester is not needed for the built-in tests. If your custom tests include [Pester-format tests](../writing-tests/pester-format-tests.md) (`*.Tests.ps1`), add `Install-Module Pester -MinimumVersion 5.7.1 -Force` before running Maester.
:::
## Manually running the Maester tests
To manually run the Maester tests workflow
- Open your Maester Bitbucket repository.
- Select **Piplines** from the left pane
- Click Run pipeline on the top right pane.
- Select the branch you want to run the pipeline on (e.g., main) , select the Pipeline `custom:run-maester-tests` and click Run.
- This will trigger the pipeline.
## Viewing the test results
- Open your Maester Bitbucket repository and go to Pipelines.
- Click on the latest pipeline run to inspect. Click on the **Run Maester Tests** step and select the **artifacts** tab on right.
- Click on the download icon to download the test results artifacts.
- Open the folder `test-results` from the downloaded artifact to view the test results.
- Click on the `test-results.html` page to view the test result in your browser.\
## Schedule the Pipeline
- Go to the `Maester-Tests` repository in Bitbucket.
- Click **Pipelines** then Schedules (at the top right), and then click **New schedule**.
- Choose the **Branch** (e.g. main) and **Pipeline** `custom:run-maester-tests`:
- Select how often you would like the pipeline to run (e.g. weekly).
## Keeping your Maester tests up to date
The built-in tests are updated with the Maester module. Because the pipeline runs `Install-Module Maester -Force`, every run uses the latest release. To control when you upgrade, pin a version instead, for example `Install-Module Maester -RequiredVersion 3.0.0 -Force`. If you set up this pipeline with Maester 2.x, see [Upgrading from 2.x](../upgrading-from-2x.md).
## FAQ / Troubleshooting
- Ensure you are monitoring your BitBucket Runner cost.