Skip to content

README.md

Latest commit

 

History

History
196 lines (139 loc) · 6.58 KB

README.md

File metadata and controls

196 lines (139 loc) · 6.58 KB

Azure DevOps Rust API

Crates.io docs.rs License: MIT

azure_devops_rust_api implements a Rust interface to the Azure DevOps REST API (version 7.1).

The crate is autogenerated from the Azure DevOps OpenAPI spec.

Getting started

  1. Add the crate to your Cargo.toml, enabling the feature(s) you need:
[dependencies]
azure_devops_rust_api = { version = "0.37.0", features = ["git", "pipelines"] }
  1. Set environment variables:
export ADO_ORGANIZATION=<organization-name>
export ADO_PROJECT=<project-name>

  1. Authenticate — see the Authentication section below.

  2. Create a client and call the API — see the Usage section and examples.

Authentication

Two authentication methods are supported:

Azure CLI (recommended for development)

Run az login once, then:

use azure_devops_rust_api::Credential;
use azure_identity::AzureCliCredential;

let cli_credential = AzureCliCredential::new(None)?;
let credential = Credential::from_token_credential(cli_credential);

Personal Access Token (PAT)

Create a PAT with the minimum required scopes and a short expiry, then:

use azure_devops_rust_api::Credential;

let token = std::env::var("ADO_TOKEN").expect("Must define ADO_TOKEN");
let credential = Credential::from_pat(token);

Note: Treat PATs like passwords — grant only the minimum required scopes and set a short expiry.

Usage

All modules follow the same pattern:

  1. Obtain a Credential (see Authentication above).
  2. Create a top-level client via <module>::ClientBuilder::new(credential).build().
  3. Obtain a sub-client for the resource you want (e.g. repositories_client()).
  4. Call the operation method. Mandatory parameters are positional arguments; optional parameters are set via builder methods. Finalize and send the request by .awaiting the builder (the builder implements IntoFuture).

Example

use anyhow::Result;
use azure_devops_rust_api::git;
use azure_devops_rust_api::Credential;
use azure_identity::AzureCliCredential;
use std::env;

#[tokio::main]
async fn main() -> Result<()> {
    // Authenticate using the Azure CLI
    let credential = Credential::from_token_credential(AzureCliCredential::new(None)?);

    let organization = env::var("ADO_ORGANIZATION").expect("Must define ADO_ORGANIZATION");
    let project = env::var("ADO_PROJECT").expect("Must define ADO_PROJECT");

    // Create a git client
    let git_client = git::ClientBuilder::new(credential).build();

    // List all repositories in the project
    let repos = git_client
        .repositories_client()
        .list(organization, project)
        .await?
        .value;

    for repo in repos.iter() {
        println!("{}", repo.name);
    }
    println!("{} repos found", repos.len());

    Ok(())
}

See examples/git_repo_list.rs for the full runnable version.

Available features

Each Azure DevOps API area is a separate, opt-in feature. Enable only the ones you need.

Feature Description
git Repositories, pull requests, commits, branches
build Build definitions and pipeline runs
pipelines YAML pipelines
release Release definitions and deployments
wit Work items and queries
test / test_plan / test_results Test management
artifacts Azure Artifacts feeds and packages
artifacts_download Higher-level Universal Package download client (see below)
wiki Wikis and pages
graph Users, groups, and memberships
core Projects and teams
distributed_task Agent pools, task groups, environments
policy Branch policies
security Security namespaces and ACLs
search Code, work item, and wiki search
tfvc Team Foundation Version Control
profile User profiles
audit Audit log
hooks Service hooks
status Service health
work Boards, sprints, and backlogs

See the [features] section of Cargo.toml for the complete list.

Artifact downloads

In addition to the auto-generated REST API wrappers, the crate includes a higher-level artifacts_download module for downloading Universal Packages from Azure Artifacts.

Unlike the other modules, artifacts_download is not a thin wrapper around a single REST endpoint. It implements the full dedup-based download protocol: discovering service URLs, fetching package metadata, resolving blob IDs, downloading and decompressing content chunks, and reassembling them into files on disk.

Enable it with the artifacts_download feature:

[dependencies]
azure_devops_rust_api = { version = "0.37.0", features = ["artifacts_download"] }

See examples/download_artifact.rs for a full usage example.

Run the example:

cargo run --example download_artifact --features="artifacts_download" -- \
    --feed <feed> --name <package-name> --version <version> --path <output-dir>

Examples

The examples/ directory contains runnable examples for most API areas.

Run an example:

cargo run --example git_repo_get --features="git" -- <repo-name>

If you omit the required --features flag you will get a helpful error message listing what is needed.

Minimum supported Rust version (MSRV)

This crate requires Rust 1.80.0 or later.

Issue reporting

Please raise bugs and feature requests via GitHub Issues.

If the issue is in the underlying OpenAPI spec (wrong types, missing fields, incorrect paths), it is better raised against vsts-rest-api-specs, as fixes there will automatically flow into this crate on the next regeneration.

Useful links
⬇