devops_utils.core.azure_devops.builds module

Build (pipeline run) queries against the Azure DevOps REST API.

Uses only documented, non-preview Build endpoints so it works on both Services (cloud) and Server (on-prem).

devops_utils.core.azure_devops.builds.add_build_tags(client: AzureDevOpsClient, project: str, build_id: int, tags: list[str]) → list[str]

Add tags to a build and return the build’s resulting tag list.

devops_utils.core.azure_devops.builds.get_build(client: AzureDevOpsClient, project: str, build_id: int) → dict[str, Any]

Fetch a single build by id (trimmed).

devops_utils.core.azure_devops.builds.get_build_log(client: AzureDevOpsClient, project: str, build_id: int, log_id: int, *, start_line: int | None = None, end_line: int | None = None) → str

Fetch a build log’s content as plain text.

Parameters:

end_line (start_line /) – Optional line range. To tail, set start_line to line_count - N (from list_build_logs()).

devops_utils.core.azure_devops.builds.get_build_timeline(client: AzureDevOpsClient, project: str, build_id: int) → list[dict[str, Any]]

Fetch a build’s timeline: its stages/phases/jobs/tasks with status.

Each record carries a log_id (when the step produced a log) that can be passed to get_build_log(), and issues with the step’s error and warning messages — the fastest way to locate why a run failed.

Returns:

Timeline records sorted by their order, trimmed to {id, parent_id, type, name, state, result, log_id, start_time, finish_time, issues}.

devops_utils.core.azure_devops.builds.list_build_logs(client: AzureDevOpsClient, project: str, build_id: int) → list[dict[str, Any]]

List a build’s logs as {id, line_count} entries.

Use line_count with get_build_log()’s start_line to tail a large log instead of downloading it whole.

devops_utils.core.azure_devops.builds.list_builds(client: AzureDevOpsClient, project: str, *, definitions: list[int] | None = None, branch: str | None = None, statuses: list[str] | None = None, results: list[str] | None = None, top: int = 25) → list[dict[str, Any]]

List builds in a project, newest first (API default order).

Parameters:

• definitions – Optional pipeline definition ids to filter on.

• branch – Optional source branch (short names get refs/heads/ prefixed).

• statuses – Optional status filter values (inProgress, completed, notStarted, cancelling, postponed).

• results – Optional result filter values (succeeded, partiallySucceeded, failed, canceled).

• top – Maximum number of builds to return.

devops_utils.core.azure_devops.builds.list_definitions(client: AzureDevOpsClient, project: str, *, name: str | None = None, top: int = 25) → list[dict[str, Any]]

List build (pipeline) definitions in a project.

Parameters:

• name – Optional definition name filter; * wildcards are supported by the API (e.g. CI*).

• top – Maximum number of definitions to return.