azure-devops

An idiomatic Rust client for the Azure DevOps REST APIs.

Built with reference to the official azure-devops-node-api library and Microsoft's REST API documentation.

Installation

[dependencies]
azure-devops = "0.1"

Quick Start

use azure_devops::AzureDevOps;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = AzureDevOps::builder()
        .organization("my-company")
        .pat(std::env::var("AZURE_DEVOPS_PAT")?)
        .build()?;

    let projects = client.projects().list().await?;

    for project in &projects.value {
        println!("{}", project.name);
    }

    Ok(())
}

Current API Coverage

API Area	Client	Key Operations
Projects	ProjectsClient	list, get, list_with_options, get_with_options
Work Items	WorkItemsClient	create, get, update, delete, destroy, query_by_wiql, get_batch, get_many, types, fields, states, state colors
Repositories	RepositoriesClient	list, get, create, delete, branches, commits, refs, items (files), pushes, statuses
Pull Requests	PullRequestsClient	list, get, create, update, comments, threads, reviewers, commits, work item refs
Builds	BuildsClient	list, get, get_latest, queue, definitions, artifacts, logs, timeline, tags, changes, metrics
Pipelines	PipelinesClient	list, get, create, run, preview, runs, logs, artifacts

Type note: Most list methods return Vec<T> directly (not a wrapper). The ProjectsClient::list() and BuildsClient::list()/list_definitions() are exceptions that return paginated wrappers with .value and .count fields.

Examples

The crate ships with Runnable examples in the examples/ directory:

Example	API Area	Run with
list_projects	Projects	cargo run --example list_projects
work_items	Work Items	cargo run --example work_items
builds	Builds	cargo run --example builds
pipelines	Pipelines	cargo run --example pipelines
pull_requests	Pull Requests	cargo run --example pull_requests
repositories	Repositories	cargo run --example repositories

Set environment variables before running:

export AZURE_DEVOPS_PAT="your-personal-access-token"
export AZURE_DEVOPS_ORG="your-org-name"
export AZURE_DEVOPS_PROJECT="your-project-name"    # optional
export AZURE_DEVOPS_REPO_ID="repo-uuid"             # for pull_requests example
cargo run --example builds

AI-Assisted Development

This crate is designed for excellent AI coding assistant support:

• AGENTS.md — Comprehensive usage guide for Copilot, Claude, Cursor, and other AI tools
• .cursor/rules/ — Cursor-specific rules for code generation
• CLAUDE.md — Quick reference for Claude Code
• .github/copilot-instructions.md — GitHub Copilot instructions

Every public API method, struct, and enum has doc comments with examples. Module-level docs provide Runnable examples for each API area.

Authentication

Currently supports Personal Access Token (PAT) authentication:

AzureDevOps::builder()
    .organization("my-company")
    .pat("your-pat-token")
    .build()?;

PATs are stored using secrecy::SecretString — they will not appear in Debug output or logs.

API Design

The library provides a fluent, strongly-typed API:

// List projects
let projects = client.projects().list().await?;

// Get a specific project
let project = client.projects().get("my-project").await?;

// With options
use azure_devops::projects::models::{ListProjectsOptions, ProjectStateFilter};

let opts = ListProjectsOptions {
    state_filter: Some(ProjectStateFilter::WellFormed),
    top: Some(10),
    ..Default::default()
};
let projects = client.projects().list_with_options(&opts).await?;

Error Handling

All methods return Result<T, AzureDevOpsError>. The error type distinguishes:

• Network failures
• Authentication errors (401/403)
• API errors (with HTTP status and message)
• Serialization failures
• Rate limiting (429)
• Configuration errors

Minimum Supported Rust Version

Rust 1.75 or later (2021 edition).

License

MIT