Azure DevOps

Proofroom reads Azure DevOps (REST API 7.1) as an Entra app registration with the client-credentials flow and files five kinds of evidence. Add it on Integrations → Catalogue → Azure DevOps → Connect.

What each collector shows

Collector	Kind	Default cadence	What it shows	Suggested controls
Pull-request reviews	window	monthly	Pull requests completed in the window with reviewers, votes and policy evaluations, plus the branch policy configuration. A pull request counts as reviewed when someone other than the author approved it (“Approved” or “Approved with suggestions”), whether they were a required or an optional reviewer; the author’s own vote never counts. When the votes show no such approval, a passed Minimum number of reviewers policy that does not count the creator’s vote is accepted as Azure DevOps’ own record of one.	PCI DSS 6.5.1–6.5.4; SOC 2 CC8.1
Pipeline runs	window	monthly	Pipeline runs finished in the window with their result and approvals, plus the checks configured on each environment.	PCI DSS 6.5.5; SOC 2 CC8.1
Work-item changes	window	monthly	Work items closed in the window (of the configured types, or every type) with their state history.	PCI DSS 6.5.1; SOC 2 CC8.1
Permission reviews	snapshot	quarterly	Project and organisation group memberships, project-level permissions and Git repository permissions. Groups inside groups are expanded, so people with access through a nested Azure DevOps group are listed with the path they come through. Entra ID groups are named but their members are not listed (see Known limits).	PCI DSS 7.2.1–7.2.5, 8.2.1–8.2.8; SOC 2 CC6.1, CC6.2, CC6.3
Service connections	snapshot	quarterly	Service connections with their last-used dates, and variable groups with their secret variables (names only).	PCI DSS 8.6.1–8.6.3; SOC 2 CC6.1

Create the app registration

Register the app. Entra admin center → App registrations → New registration: name it (for example Proofroom Azure DevOps reader), single tenant, no redirect URI. Note the Directory (tenant) ID and Application (client) ID. No API permissions are needed: Azure DevOps authorises the service principal through its own user list.
Create a client secret. Certificates & secrets → New client secret. Copy the value at once and note the expiry: an expired secret fails every run with HTTP 401 from login.microsoftonline.com.
Add the service principal to the organisation. Azure DevOps → Organization settings → Users → Add users: the app registration’s name, Basic access, added to the projects to collect.
Project permissions. In each project, Readers is enough for pull requests, pipelines, work items and permissions. If Service connections or Permission reviews fails with 401 or 403, give the service principal the Reader role on the project’s service connections (Project settings → Service connections → Security); never Project Administrators.

Connect

Field	Value
Organization URL	`https://dev.azure.com/<organization>` or `https://<organization>.visualstudio.com`
Projects	Project names, one per line
Tenant ID, client ID, client secret	From the app registration
Work-item types	Types to collect, one per line; empty means all types

The connection test lists the projects the service principal can see and names any configured project it cannot.

Known limits

Policy evaluations, environment checks and the Graph API are preview-only in REST API 7.1.
The approvals API returns at most 200 approvals per request and has no next page. When a project returns a full 200, Proofroom reads each run’s approvals from its build timeline instead (one extra call per run), so the list is always complete. If an approval named in a timeline cannot be read, the run fails rather than filing a short list.
Classic release approvals (Releases, not YAML environments) are not read.
Azure DevOps does not expand Entra ID groups (its own expanded membership view does not either, and it never lists service principals in them), so Permission reviews names each Entra ID group that grants access and counts them in the summary, but does not list the people in them. Review those groups’ members in Entra ID, for example with the Entra ID connector.
Nested groups are expanded up to 1,000 groups in one run; past that the run fails rather than file a partial list.
The token is sent only to dev.azure.com or an <organization>.visualstudio.com address over https.

When the client secret expires

Proofroom reads when the app registration’s client secret expires and warns admins 30 and 7 days before (the integration page lists it under Credentials, named by the secret’s description and the last four characters of its key ID, for example Client secret "Proofroom" (…a1b2); never by any part of the secret). This needs the Microsoft Graph application permission Application.Read.All with admin consent. It is optional, and it is tenant-wide: it lets the app read every app registration in the tenant, not just its own. You may prefer to skip it and track the secret’s expiry date yourself. Without it, the integration page notes that the expiry could not be read, and nothing else changes.