Documentation

Overview

ADOScore connects to your Azure DevOps organization using a scoped Personal Access Token (PAT) you provide. It reads commit history, pull request records, and file change metadata from the ADO REST API, then runs a scoring pipeline to produce per-developer activity and security risk scores. Results are stored historically so you can track trends over time.

No source code is stored. ADOScore only reads file paths, commit metadata, and — in Deep Scan mode — fetches file content transiently to run pattern matching. File content is never persisted.

How It Works

Each scoring run executes the following pipeline stages in order. All ADO API calls are read-only.

Data Collection

ADOScore reads the following fields from the Azure DevOps REST API. All calls are authenticated with the PAT you provide and are strictly read-only — ADOScore never writes to your ADO organization.

Commit metadata

File change paths

Pull request metadata

File content (Deep Scan only)

In Deep Scan mode, text file content is fetched transiently and scanned with regex patterns. The content is processed in memory and immediately discarded — it is never written to disk, logs, or the database. Binary file extensions are blocklisted and skipped entirely.

Data in Transit

All communication between ADOScore and Azure DevOps uses HTTPS. All communication between your browser and ADOScore uses HTTPS. The decrypted PAT is only present in server memory during an active scoring run and is never sent to the client.

What does NOT leave your ADO organization

Commit message bodies, code diffs, file content (except transiently during Deep Scan), branch names beyond what is stored in PR metadata, user profile photos, and any ADO work items (tickets, boards) are never fetched or transmitted.

Data at Rest

ADOScore stores the minimum data required to display dashboards and historical trends. All data is stored in a PostgreSQL database hosted on Neon (serverless Postgres).

File content, commit diffs, and commit messages are never stored. Risk factors stored in developer_scores.risk_factors contain only structured strings such as Direct push to main in repo-name or Sensitive file: .env — never raw file content.

PAT Security

Encryption

Personal Access Tokens are encrypted with AES-256-GCM before being written to the database. A unique 16-byte random IV is generated per encryption operation. The authentication tag produced by GCM mode is stored alongside the ciphertext, providing integrity verification on decryption.

// Encryption model
algorithm:  AES-256-GCM
key:        32-byte random key (hex-encoded in environment variable)
iv:         16-byte random, generated per-PAT, stored in orgs.pat_iv
auth_tag:   appended to ciphertext as hex, verified on decrypt
plaintext:  never written to disk, logs, or database

PAT Lifecycle

Required PAT Scopes

ADOScore only requires read-only scopes. Grant the minimum permissions when creating your PAT in Azure DevOps.

Scoring Methodology

Activity Score (0–100, higher = more active)

Security Risk Score (0–100, higher = more risk)

Total is clamped to 100.

Risk Tiers

Secret Detection Patterns

The following patterns are scanned during Deep Scan runs. Matching is performed against file content in memory — no content is stored regardless of whether a match is found.

Sensitive File Patterns

These file path patterns trigger a risk finding regardless of file content. Deep Scan is not required.

API Reference

All authenticated endpoints require a valid session cookie issued by the NextAuth session system. Requests without a valid session return 401 Unauthorized. Org-scoped endpoints additionally verify that the authenticated user owns the requested org.

Authentication

{ "email": "user@example.com", "password": "…" }

Set-Cookie: authjs.session-token=…

Organizations

{
  "displayName": "Contoso Engineering",
  "orgUrl": "https://dev.azure.com/contoso",
  "pat": "…",
  "adoProject": "MyProject",
  "daysBack": 30,
  "deepScan": false,
  "scheduleHours": 24
}

{
  "org": { "id": "…", "displayName": "…", "orgUrl": "…", "patHint": "abcd" },
  "project": { "id": "…", "adoProject": "…" }
}

{
  "id": "…",
  "displayName": "…",
  "orgUrl": "…",
  "patHint": "abcd",
  "projects": [ { "id": "…", "adoProject": "…", "scheduleHours": 24 } ]
}

{ "displayName": "New Name" }
// or for PAT rotation:
{ "pat": "new-pat-value" }

{ "ok": true }

{ "ok": true }

{ "pat": "…" }

{
  "ok": true,
  "projects": ["ProjectAlpha", "ProjectBeta"]
}
// on failure:
{ "ok": false, "error": "Authentication failed" }

Projects & Scoring

{
  "adoProject": "MyProject",
  "daysBack": 30,
  "deepScan": false,
  "scheduleHours": 24,
  "protectedBranches": ["main", "master"],
  "alertOnCritical": true
}

{ "id": "…", "adoProject": "MyProject", … }

{ "runId": "…" }

[
  {
    "id": "…",
    "status": "complete",
    "triggeredBy": "manual",
    "startedAt": "2026-04-13T00:00:00Z",
    "completedAt": "2026-04-13T00:02:14Z",
    "devCount": 12,
    "highRiskCount": 2
  }
]

Cron (internal)

{ "triggered": 3, "errors": [] }

Error Responses