# azure-devops
An idiomatic Rust client for the [Azure DevOps REST APIs](https://learn.microsoft.com/en-us/rest/api/azure/devops/).
Built with reference to the official [azure-devops-node-api](https://github.com/Microsoft/azure-devops-node-api) library and Microsoft's REST API documentation.
## Installation
```toml
[dependencies]
azure-devops = "0.1"
```
## Quick Start
```rust
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
| **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/`](examples/) directory:
| [`list_projects`](examples/list_projects.rs) | Projects | `cargo run --example list_projects` |
| [`work_items`](examples/work_items.rs) | Work Items | `cargo run --example work_items` |
| [`builds`](examples/builds.rs) | Builds | `cargo run --example builds` |
| [`pipelines`](examples/pipelines.rs) | Pipelines | `cargo run --example pipelines` |
| [`pull_requests`](examples/pull_requests.rs) | Pull Requests | `cargo run --example pull_requests` |
| [`repositories`](examples/repositories.rs) | Repositories | `cargo run --example repositories` |
Set environment variables before running:
```sh
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`](AGENTS.md)** — Comprehensive usage guide for Copilot, Claude, Cursor, and other AI tools
- **[`.cursor/rules/`](.cursor/rules/)** — Cursor-specific rules for code generation
- **[`CLAUDE.md`](CLAUDE.md)** — Quick reference for Claude Code
- **[`.github/copilot-instructions.md`](.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:
```rust
AzureDevOps::builder()
.organization("my-company")
.pat("your-pat-token")
.build()?;
```
PATs are stored using [`secrecy::SecretString`](https://docs.rs/secrecy) — they will not appear in `Debug` output or logs.
## API Design
The library provides a fluent, strongly-typed API:
```rust
// 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