Howto

Run the ADO Health Check

The latest adohealth CLI — install command first, zip fallback, how to verify a download, local and Azure Pipelines run steps, and how to book a Mentat assessment on the findings.

How to run

From download to first report

01

Install with the gated command

Complete email + code verification, then run the copy-paste command from the download page. It installs adohealth on your PATH for the matching macOS or Linux build and checks SHA256 before chmod. When gpg is installed it also verifies the SHA256SUMS signature against the Mentat release key and stops on a bad signature. Windows builds are in the zip, not this command.

02

Or download the zip instead

The same page still offers ado-health-check-cli.zip: the latest adohealth build for linux/darwin/windows × amd64/arm64, plus SHA256SUMS, the signature SHA256SUMS.asc, the release public key adohealth-release.asc, and README.txt. Verify it (see Verify a download below), then chmod +x the adohealth-<version>-<os>-<arch> file (or run the Windows .exe) and use that file in place of the installed command.

03

Authenticate and run locally

Set ADO_PAT (or AZURE_DEVOPS_EXT_PAT) to a PAT with read on Build, Code, and Agent Pools — or rely on git credential fill for host=dev.azure.com. Then run adohealth -org YOUR_ORG -project YOUR_PROJECT -no-open.

04

Run in Azure Pipelines

Copy the pipeline snippet below onto a linux agent job. Pass System.AccessToken as ADO_PAT (ensure the job allows OAuth token access). Replace YOUR_ORG with your Azure DevOps organization name.

Local command

Install, then run on your workstation

Replace TOKEN with the short-lived token from the download page, then YOUR_ORG / YOUR_PROJECT. The installer puts adohealth on PATH (/usr/local/bin if writable, otherwise ~/.local/bin). Zip fallback: run the versioned binary from the archive the same way. Progress goes to stderr; JSON and HTML write to files. Use -version to confirm the binary.

# After the email code is accepted, copy this from the download page.
# TOKEN is the short-lived download token. The script picks Mac or Linux, checks SHA256,
# and checks the GPG signature on SHA256SUMS when gpg is installed.
curl -fsSL "https://www.mentat.cloud/api/install-adohealth?token=TOKEN" | sh

export ADO_PAT='***'   # PAT with read on Build, Code, Agent Pools
adohealth -org YOUR_ORG -project YOUR_PROJECT -no-open

Verify

Verify a download

Each release ships SHA256SUMS and a detached GPG signature, SHA256SUMS.asc, made by ADOHealth Release Bot <adohealth-release@mentat.cloud>, the same key that signs adohealth git tags. The signature proves the checksums came from the release pipeline; sha256sum -c then proves each binary matches them. Download the public key from this site or use the copy in the zip.

Primary fingerprint: F121 4D56 FADF 5058 F9B8 C9D8 9F4B AAB0 532A 21E6 (key ID 9F4BAAB0532A21E6). Trust this primary fingerprint, not a subkey ID alone.

# 1. Get the public key (it is also in the zip as adohealth-release.asc)
curl -fsSLO https://www.mentat.cloud/downloads/adohealth-release.asc
gpg --import adohealth-release.asc

# 2. Check the primary fingerprint
gpg --fingerprint 'ADOHealth Release Bot <adohealth-release@mentat.cloud>'
#    must show: F121 4D56 FADF 5058 F9B8  C9D8 9F4B AAB0 532A 21E6
# 3. In the unzipped folder: authenticate SHA256SUMS, then check the binaries
gpg --verify SHA256SUMS.asc SHA256SUMS

sha256sum -c SHA256SUMS          # Linux
shasum -a 256 -c SHA256SUMS      # macOS

# Only kept one binary? Add --ignore-missing (Linux) or check that one line by hand.

# 4. Confirm the version and commit of the binary you will run
./adohealth-<version>-<os>-<arch> -version

What a good result looks like

  • gpg: Good signature from "ADOHealth Release Bot <adohealth-release@mentat.cloud>". GnuPG names the signing subkey EFCE6A1087602A44110C278A4E962ED8D6853A0C; that is expected.
  • WARNING: This key is not certified with a trusted signature! only means you have not marked the key as trusted. The signature is still good if the fingerprint matches.
  • Every file in sha256sum -c reports OK.

Stop if

  • GnuPG prints BAD signature, or the fingerprint differs from the one above.
  • Any checksum fails. Do not run a binary whose checksum does not match.
  • Releases before v0.5.3 have no SHA256SUMS.asc. For those, SHA256SUMS only catches corruption; it is not a signature.
# Windows (PowerShell, with Gpg4win for gpg)
gpg --import adohealth-release.asc
gpg --verify SHA256SUMS.asc SHA256SUMS
Get-FileHash .\adohealth-<version>-windows-amd64.exe -Algorithm SHA256
# Compare the hash (case-insensitive) with that file's line in SHA256SUMS.

macOS Gatekeeper may quarantine the unsigned binaries and Windows SmartScreen may warn on the .exe; Apple notarization and Authenticode are not in place yet. The GPG signature on SHA256SUMS is the authenticity check.

Azure Pipelines

Wire it into a pipeline job

Linux agent example. Place the binary under $(Pipeline.Workspace)/adohealth/ (secure file, prior artifact download, or checked-in tool cache). Enable “Allow scripts to access the OAuth token” when using $(System.AccessToken).

steps:
- bash: |
    set -euo pipefail
    BIN=$(find "$(Pipeline.Workspace)/adohealth" -type f -name 'adohealth-*-linux-amd64' | sort -V | tail -n 1)
    test -n "$BIN"
    chmod +x "$BIN"
    "$BIN" -org YOUR_ORG -project "$(System.TeamProject)" \
      -out "$(Agent.TempDirectory)/ado-pipeline-inventory.json" \
      -html "$(Agent.TempDirectory)/ado-health.html" \
      -no-open -quiet
  env:
    ADO_PAT: $(System.AccessToken)
  displayName: Run ADO Health Check

Report

What the report describes

A successful run writes JSON inventory (-out, default ado-pipeline-inventory.json) and an HTML report (-html). CI / -no-open skips launching a browser.

Pipeline hygiene

Coverage of YAML vs classic, required checks, retention, and failed-run trends.

Identity & access

Service connections, variable group secrecy, project admin sprawl, and guest access signals.

Agent & pool posture

Self-hosted vs Microsoft-hosted mix, single points of failure, and version drift.

Recommended next moves

A short, prioritized backlog you can hand to platform or DevOps owners — or bring to a Mentat assessment.

Book an Assessment

Prefer a guided readout? Mentat will walk your health-check themes, score maturity, and leave 3–5 concrete next moves. Continues to the Assessment page.

Book an Assessment