> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure DevOps Repos Tools

> Connect Genesis to Azure Repos so agents can list repositories and branches, read files and directory trees, search code by text or regex, inspect commits and diffs, review pull requests and policy statuses, and read Advanced Security alerts.

## **Overview**

<Note>
  Before using this tool group, save an Azure DevOps connection as described in
  [Azure DevOps](/docs/Setup/Azure-DevOps). If `connection_id` is omitted, the
  tools use the effective default `azure_devops` connection for the current
  user (My default, then Role default). Actions that need a project use the
  explicit `project` parameter first and otherwise fall back to the connection's
  saved default `project`. The PAT needs the **Code (Read)** scope;
  `ado_list_security_alerts` additionally needs **Advanced Security (alerts
  read)**.
</Note>

### **Tool Name**

```json theme={null}
azure_devops_repos_tools
```

### **Purpose**

The **azure\_devops\_repos\_tools** group gives Genesis read access to Azure
Repos: repository and branch inventory, file and directory reads by branch or
commit, full-text and regex code search with line numbers and context
snippets, commit details and diffs, filtered pull request listings with review
threads and policy statuses, and Advanced Security alerts categorized across
code, secret, and dependency scanning.

This group is read-only. Cloning, committing, pushing, and creating or
completing pull requests go through the existing `git_action` tool surface.

### **Key Features**

<Steps>
  <Step title="Browse repositories and branches" icon="folder-tree">
    List a project's repositories with paging, and its branches with optional
    latest-commit metadata (author, date, ahead/behind counts).
  </Step>

  <Step title="Read files and directory trees" icon="file-lines">
    Fetch full file content up to 1 MB by branch or commit; larger, binary,
    and size-unknown files return a blob URL for download instead. List
    folders one level or recursively.
  </Step>

  <Step title="Search code by text or regex" icon="magnifying-glass-code">
    Full-text search across a repo, project, or the whole org, plus
    regex scanning of one repository — both returning line numbers and
    surrounding context.
  </Step>

  <Step title="Inspect commits and diffs" icon="code-compare">
    Get commit details with changed files, compare any two commits or
    branches, and render per-file diffs as unified text, side-by-side rows, or
    raw before/after content.
  </Step>

  <Step title="Review pull requests" icon="code-pull-request">
    Filter PRs by state, author, reviewer, or branch; read review threads and
    completion state; check policy gates (build, reviewers) and merge
    conflicts.
  </Step>

  <Step title="Read Advanced Security alerts" icon="shield-halved">
    List code-scanning, secret-scanning, and dependency alerts, categorized
    and filterable by state and severity.
  </Step>
</Steps>

## **Input Parameters for Each Function**

Every function also accepts an optional `connection_id` (Azure DevOps
connection name; the effective default connection is used when omitted) and an
optional `project` (falls back to the connection's default project).

### **`ado_list_repos`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`top`** | Integer | `None` | Maximum number of repositories to return. |
| **`skip`** | Integer | `None` | Number of repositories to skip (paging). |

Returns `repositories` and `total_count` (the full list length before paging).

### **`ado_list_branches`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`repo`** | String | none | Required. Repository name or id. |
| **`name_filter`** | String | `None` | Case-insensitive contains filter on branch names. |
| **`include_metadata`** | Boolean | `false` | When true, each branch carries its latest commit (author, date) and ahead/behind counts. |
| **`top`** | Integer | `None` | Maximum number of branches to return. |
| **`continuation_token`** | String | `None` | Continuation token from a previous page. |

### **`ado_read_file`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`repo`** | String | none | Required. Repository name or id. |
| **`path`** | String | none | Required. File path, e.g. `/src/app.py`. |
| **`branch`** | String | default branch | Branch to read from. |
| **`commit`** | String | `None` | Full commit SHA to read from instead of a branch. |

Files up to 1 MB return full inline `content`. Larger files, binary
files, and files whose size the API cannot report return `blob_url`,
`size`, `over_size_limit`, and when size was unavailable `size_unknown`
instead of inline `content`.

### **`ado_list_directory`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`repo`** | String | none | Required. Repository name or id. |
| **`path`** | String | `/` | Directory to list. |
| **`branch`** / **`commit`** | String | default branch | Version to list from. |
| **`recursive`** | Boolean | `false` | Walk the whole subtree in one call. |

### **`ado_search_code`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`query`** | String | none | Required. Search text (`mode="text"`) or Python regex (`mode="regex"`). |
| **`mode`** | String | `text` | `text` uses ADO full-text search; `regex` scans one repository's files. |
| **`repo`** | String | `None` | Repository to search. Optional for text mode, required for regex mode. |
| **`path`** | String | `None` | Path prefix to narrow the search, e.g. `/models`. |
| **`branch`** | String | default branch | Branch to search. |
| **`top`** | Integer | `25` | Maximum full-text hits requested from ADO. |
| **`max_files_scanned`** | Integer | `20` | Upper bound on files fetched for line-level matching (max 100). |
| **`context_lines`** | Integer | `2` | Lines of context around each match. |

### **`ado_get_commit`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`repo`** | String | none | Required. Repository name or id. |
| **`commit_id`** | String | none | Required. Full commit SHA. |
| **`include_changes`** | Boolean | `true` | Include the commit's changed files and change counts. |

### **`ado_get_commit_diff`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`repo`** | String | none | Required. Repository name or id. |
| **`base_version`** | String | none | Required. Base commit SHA or branch name. |
| **`target_version`** | String | none | Required. Target commit SHA or branch name. |
| **`path`** | String | `None` | File path for a line-level diff; omit for the repo-wide change summary. |
| **`diff_format`** | String | `unified` | `unified`, `side_by_side`, or `raw`. |
| **`base_version_type`** / **`target_version_type`** | String | `commit` | How to interpret the versions: `commit` or `branch`. |

### **`ado_list_pull_requests`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`repo`** | String | none | Required. Repository name or id. |
| **`status`** | String | `active` | `active`, `completed`, `abandoned`, or `all`. |
| **`creator_id`** | String | `None` | ADO identity GUID of the PR author. |
| **`reviewer_id`** | String | `None` | ADO identity GUID of a reviewer. |
| **`source_branch`** | String | `None` | Source branch filter (bare name or full ref). |
| **`target_branch`** | String | `None` | Target branch filter (bare name or full ref). |
| **`top`** / **`skip`** | Integer | `None` | Paging. |

### **`ado_get_pull_request_threads`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`repo`** | String | none | Required. Repository name or id. |
| **`pull_request_id`** | Integer | none | Required. Pull request id. |

Returns the PR summary (`status`, `merge_status`, `is_draft`, `closed_date`)
plus every review thread with its status and comments.

### **`ado_get_pull_request_policies`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`repo`** | String | none | Required. Repository name or id. |
| **`pull_request_id`** | Integer | none | Required. Pull request id. |

Returns one evaluation per configured policy (build, minimum reviewers, …)
with its status, plus `merge_status` — `conflicts` means the PR cannot merge.

### **`ado_list_security_alerts`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`repo`** | String | none | Required. Repository name or id. |
| **`alert_type`** | String | `None` | `code`, `secret`, or `dependency`. |
| **`states`** | String or Array | `None` | Alert states to include, e.g. `active` or `["active", "fixed"]`. |
| **`severities`** | String or Array | `None` | Severities to include, e.g. `critical` or `["critical", "high"]`. |
| **`top`** | Integer | `None` | Maximum number of alerts. |
| **`continuation_token`** | String | `None` | Continuation token from a previous page. |

Results come back as `alerts_by_category` with `code`, `secret`, and
`dependency` lists plus per-category counts.

## **Usage Patterns**

### Code search examples

```text theme={null}
# Literal text across the whole org
ado_search_code(query="fivetran")

# Scoped full-text search with more context
ado_search_code(query="warehouse_size", project="Analytics",
                repo="dbt-models", path="/models", context_lines=4)

# Regex scan of one repository (regex mode requires repo)
ado_search_code(query="AKIA[0-9A-Z]{16}", mode="regex",
                repo="infra", path="/terraform")
```

Each result carries `line_number`, the matched `line`, and a `context`
snippet. Regex scanning is bounded by `max_files_scanned` and reports
`truncated: true` when the tree is larger — narrow with `path` in that case.

### PR filtering patterns

```text theme={null}
# Open PRs targeting main
ado_list_pull_requests(repo="dbt-models", target_branch="main")

# Everything a specific author completed
ado_list_pull_requests(repo="dbt-models", status="completed",
                       creator_id="<identity-guid>")

# Review state and policy gates for one PR
ado_get_pull_request_threads(repo="dbt-models", pull_request_id=77)
ado_get_pull_request_policies(repo="dbt-models", pull_request_id=77)
```

`creator_id` and `reviewer_id` take ADO identity GUIDs (from
`createdBy.id` / `reviewers[].id` of a previous listing), not display names.

## **Error Handling and Throttling**

Failures return `success: false` with an explicit `error_type`: `auth` (401 —
bad or expired PAT), `permission` (403 — missing PAT scope), `not_found`
(404 — wrong repo/path/commit), `rate_limit` (429 — the result carries
`retry_after_seconds` from the ADO `Retry-After` header; wait that long before
retrying), or `api`. Listings that page server-side return a
`continuation_token` to pass into the next call.