Git Repositories API Reference

Git Repositories API Reference

Comprehensive reference for Azure DevOps Git REST API operations.

Table of Contents

• Repository Concepts
• Pull Request Operations
• Branch Policies
• Git Refs and Commits
• Code Review

Repository Concepts

Repository Properties

Ref Format

refs/heads/main          # Branch
refs/heads/feature/test  # Feature branch
refs/tags/v1.0.0         # Tag
refs/pull/123/merge      # PR merge ref

Pull Request Operations

PR Status Values

Merge Strategies

PR Vote Values

PR Completion Options

{
  "autoCompleteSetBy": {
    "id": "user-guid"
  },
  "completionOptions": {
    "deleteSourceBranch": true,
    "mergeCommitMessage": "Merged PR #123: Feature description",
    "mergeStrategy": "squash",
    "bypassPolicy": false,
    "bypassReason": "",
    "transitionWorkItems": true,
    "squashMerge": true
  }
}

Branch Policies

Policy Types

Policy Configuration Example

{
  "isEnabled": true,
  "isBlocking": true,
  "type": {
    "id": "fa4e907d-c16b-4a4c-9dfa-4916e5d171ab"
  },
  "settings": {
    "minimumApproverCount": 2,
    "creatorVoteCounts": false,
    "allowDownvotes": false,
    "resetOnSourcePush": true,
    "scope": [
      {
        "refName": "refs/heads/main",
        "matchKind": "exact",
        "repositoryId": "repo-guid"
      }
    ]
  }
}

Git Refs and Commits

Ref Update Operation

Commit Properties

Change Types

Code Review

Thread Status

Comment Types

Thread Context

{
  "filePath": "/src/main.cs",
  "rightFileStart": {
    "line": 10,
    "offset": 1
  },
  "rightFileEnd": {
    "line": 15,
    "offset": 50
  },
  "leftFileStart": null,
  "leftFileEnd": null
}

MCP Tool Usage Examples

List Repositories

# Using mcp__ado__repo_list_repos_by_project
params = {
    "project": "MyProject",
    "repoNameFilter": "api",  # Optional filter
    "top": 100
}

Get Repository

# Using mcp__ado__repo_get_repo_by_name_or_id
params = {
    "project": "MyProject",
    "repositoryNameOrId": "my-repo"
}

Create Branch

# Using mcp__ado__repo_create_branch
params = {
    "repositoryId": "repo-guid",
    "branchName": "feature/new-feature",
    "sourceBranchName": "main"
}

List Branches

# Using mcp__ado__repo_list_branches_by_repo
params = {
    "repositoryId": "repo-guid",
    "filterContains": "feature",
    "top": 50
}

Search Commits

# Using mcp__ado__repo_search_commits
params = {
    "project": "MyProject",
    "repository": "my-repo",
    "searchText": "fix bug",
    "author": "developer@company.com",
    "fromDate": "2024-01-01T00:00:00Z",
    "toDate": "2024-12-31T23:59:59Z",
    "includeWorkItems": True,
    "top": 20
}

Create Pull Request

# Using mcp__ado__repo_create_pull_request
params = {
    "repositoryId": "repo-guid",
    "sourceRefName": "refs/heads/feature/new-feature",
    "targetRefName": "refs/heads/main",
    "title": "Add new feature",
    "description": "## Summary\nThis PR adds...\n\n## Testing\n- [ ] Unit tests\n- [ ] Integration tests",
    "isDraft": False,
    "workItems": "12345 12346"  # Space-separated IDs
}

Update Pull Request

# Using mcp__ado__repo_update_pull_request
params = {
    "repositoryId": "repo-guid",
    "pullRequestId": 123,
    "title": "Updated title",
    "description": "Updated description",
    "autoComplete": True,
    "mergeStrategy": "Squash",
    "deleteSourceBranch": True,
    "transitionWorkItems": True
}

Add/Remove Reviewers

# Using mcp__ado__repo_update_pull_request_reviewers
params = {
    "repositoryId": "repo-guid",
    "pullRequestId": 123,
    "reviewerIds": ["user-guid-1", "user-guid-2"],
    "action": "add"  # or "remove"
}

List PR Threads

# Using mcp__ado__repo_list_pull_request_threads
params = {
    "repositoryId": "repo-guid",
    "pullRequestId": 123,
    "top": 100
}

Create Comment Thread

# Using mcp__ado__repo_create_pull_request_thread
params = {
    "repositoryId": "repo-guid",
    "pullRequestId": 123,
    "content": "Please review this logic",
    "filePath": "/src/main.cs",
    "rightFileStartLine": 10,
    "rightFileEndLine": 15,
    "status": "Active"
}

Reply to Comment

# Using mcp__ado__repo_reply_to_comment
params = {
    "repositoryId": "repo-guid",
    "pullRequestId": 123,
    "threadId": 456,
    "content": "Good catch, I'll fix this."
}

Resolve Thread

# Using mcp__ado__repo_resolve_comment
params = {
    "repositoryId": "repo-guid",
    "pullRequestId": 123,
    "threadId": 456
}

Find PRs by Commit

# Using mcp__ado__repo_list_pull_requests_by_commits
params = {
    "project": "MyProject",
    "repository": "my-repo",
    "commits": ["abc123def456", "789ghi012jkl"],
    "queryType": "LastMergeCommit"
}

Git URL Patterns

Clone URLs

# HTTPS
https://dev.azure.com/{org}/{project}/_git/{repo}

# SSH
git@ssh.dev.azure.com:v3/{org}/{project}/{repo}

# With PAT
https://{pat}@dev.azure.com/{org}/{project}/_git/{repo}

Web URLs

# Repository home
https://dev.azure.com/{org}/{project}/_git/{repo}

# Specific branch
https://dev.azure.com/{org}/{project}/_git/{repo}?version=GB{branch}

# Specific file
https://dev.azure.com/{org}/{project}/_git/{repo}?path=/path/to/file&version=GB{branch}

# Commit
https://dev.azure.com/{org}/{project}/_git/{repo}/commit/{commitId}

# Pull request
https://dev.azure.com/{org}/{project}/_git/{repo}/pullrequest/{prId}

# Compare
https://dev.azure.com/{org}/{project}/_git/{repo}/branchCompare?baseVersion=GB{base}&targetVersion=GB{target}