pipelines_get_builds
Retrieve and filter Azure DevOps pipeline builds across organizations by criteria like status, time, branch, or requester to monitor and analyze CI/CD execution.
Instructions
Gets a list of builds (pipeline runs) with filtering options
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| organization | Yes | The name of the Azure DevOps organization | |
| project | Yes | Project ID or name to get builds for | |
| definitions | No | Array of build definition IDs to filter builds | |
| queues | No | Array of queue IDs to filter builds | |
| buildNumber | No | Build number to filter builds | |
| minTime | No | Minimum finish time to filter builds (ISO 8601 string) | |
| maxTime | No | Maximum finish time to filter builds (ISO 8601 string) | |
| requestedFor | No | User ID or name who requested the build | |
| reasonFilter | No | Reason filter for the build (see BuildReason enum) | |
| statusFilter | No | Status filter for the build (see BuildStatus enum) | |
| resultFilter | No | Result filter for the build (see BuildResult enum) | |
| tagFilters | No | Array of tags to filter builds | |
| properties | No | Array of property names to include in the results | |
| top | No | Maximum number of builds to return | |
| continuationToken | No | Token for continuing paged results | |
| maxBuildsPerDefinition | No | Maximum number of builds per definition | |
| deletedFilter | No | Filter for deleted builds (see QueryDeletedOption enum) | |
| queryOrder | No | Order in which builds are returned | QueueTimeDescending |
| branchName | No | Branch name to filter builds | |
| buildIds | No | Array of build IDs to retrieve | |
| repositoryId | No | Repository ID to filter builds | |
| repositoryType | No | Type of repository to filter builds |
Implementation Reference
- src/tools/pipelines.ts:127-194 (handler)The asynchronous handler function implementing the core logic of the 'pipelines_get_builds' tool. It connects to Azure DevOps, queries builds with provided filters using the Build API, simplifies the response data, and returns it as JSON text.
async ({ organization, project, definitions, queues, buildNumber, minTime, maxTime, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, properties, top, continuationToken, maxBuildsPerDefinition, deletedFilter, queryOrder, branchName, buildIds, repositoryId, repositoryType }) => { const connection = await connectionManager.getConnection(organization); const buildApi = await connection.getBuildApi(); // Default to a summary view if properties are not specified to avoid hitting token limits // We select key fields that are most useful for status checks const defaultProperties = [ "id", "buildNumber", "status", "result", "queueTime", "startTime", "finishTime", "url", "definition", "project", "sourceBranch", "requestedFor" ]; const selectedProperties = properties || defaultProperties; // Default top to 20 if not specified to prevent massive responses const limit = top || 20; const builds = await buildApi.getBuilds( project, definitions, queues, buildNumber, minTime ? new Date(minTime) : undefined, maxTime ? new Date(maxTime) : undefined, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, selectedProperties, limit, continuationToken, maxBuildsPerDefinition, deletedFilter, safeEnumConvert(BuildQueryOrder, queryOrder), branchName, buildIds, repositoryId, repositoryType ); // Simplify the output to reduce token usage const simplifiedBuilds = builds.map(b => ({ id: b.id, buildNumber: b.buildNumber, status: b.status, result: b.result, queueTime: b.queueTime, startTime: b.startTime, finishTime: b.finishTime, definition: b.definition ? { id: b.definition.id, name: b.definition.name } : undefined, sourceBranch: b.sourceBranch, requestedFor: b.requestedFor ? { displayName: b.requestedFor.displayName } : undefined, url: b.url })); return { content: [{ type: "text", text: JSON.stringify(simplifiedBuilds, null, 2) }], }; } - src/tools/pipelines.ts:99-126 (schema)Zod schema defining the input parameters for the 'pipelines_get_builds' tool, including organization, project, various filters, and pagination options.
{ organization: z.string().describe("The name of the Azure DevOps organization"), project: z.string().describe("Project ID or name to get builds for"), definitions: z.array(z.number()).optional().describe("Array of build definition IDs to filter builds"), queues: z.array(z.number()).optional().describe("Array of queue IDs to filter builds"), buildNumber: z.string().optional().describe("Build number to filter builds"), minTime: z.string().optional().describe("Minimum finish time to filter builds (ISO 8601 string)"), maxTime: z.string().optional().describe("Maximum finish time to filter builds (ISO 8601 string)"), requestedFor: z.string().optional().describe("User ID or name who requested the build"), reasonFilter: z.number().optional().describe("Reason filter for the build (see BuildReason enum)"), statusFilter: z.number().optional().describe("Status filter for the build (see BuildStatus enum)"), resultFilter: z.number().optional().describe("Result filter for the build (see BuildResult enum)"), tagFilters: z.array(z.string()).optional().describe("Array of tags to filter builds"), properties: z.array(z.string()).optional().describe("Array of property names to include in the results"), top: z.number().optional().describe("Maximum number of builds to return"), continuationToken: z.string().optional().describe("Token for continuing paged results"), maxBuildsPerDefinition: z.number().optional().describe("Maximum number of builds per definition"), deletedFilter: z.number().optional().describe("Filter for deleted builds (see QueryDeletedOption enum)"), queryOrder: z .enum(getEnumKeys(BuildQueryOrder)) .default("QueueTimeDescending") .optional() .describe("Order in which builds are returned"), branchName: z.string().optional().describe("Branch name to filter builds"), buildIds: z.array(z.number()).optional().describe("Array of build IDs to retrieve"), repositoryId: z.string().optional().describe("Repository ID to filter builds"), repositoryType: z.enum(["TfsGit", "GitHub", "BitbucketCloud"]).optional().describe("Type of repository to filter builds"), }, - src/tools/pipelines.ts:96-195 (registration)The server.tool() call that registers the 'pipelines_get_builds' tool, including its name, description, input schema, and handler function within the registerPipelineTools function.
server.tool( "pipelines_get_builds", "Gets a list of builds (pipeline runs) with filtering options", { organization: z.string().describe("The name of the Azure DevOps organization"), project: z.string().describe("Project ID or name to get builds for"), definitions: z.array(z.number()).optional().describe("Array of build definition IDs to filter builds"), queues: z.array(z.number()).optional().describe("Array of queue IDs to filter builds"), buildNumber: z.string().optional().describe("Build number to filter builds"), minTime: z.string().optional().describe("Minimum finish time to filter builds (ISO 8601 string)"), maxTime: z.string().optional().describe("Maximum finish time to filter builds (ISO 8601 string)"), requestedFor: z.string().optional().describe("User ID or name who requested the build"), reasonFilter: z.number().optional().describe("Reason filter for the build (see BuildReason enum)"), statusFilter: z.number().optional().describe("Status filter for the build (see BuildStatus enum)"), resultFilter: z.number().optional().describe("Result filter for the build (see BuildResult enum)"), tagFilters: z.array(z.string()).optional().describe("Array of tags to filter builds"), properties: z.array(z.string()).optional().describe("Array of property names to include in the results"), top: z.number().optional().describe("Maximum number of builds to return"), continuationToken: z.string().optional().describe("Token for continuing paged results"), maxBuildsPerDefinition: z.number().optional().describe("Maximum number of builds per definition"), deletedFilter: z.number().optional().describe("Filter for deleted builds (see QueryDeletedOption enum)"), queryOrder: z .enum(getEnumKeys(BuildQueryOrder)) .default("QueueTimeDescending") .optional() .describe("Order in which builds are returned"), branchName: z.string().optional().describe("Branch name to filter builds"), buildIds: z.array(z.number()).optional().describe("Array of build IDs to retrieve"), repositoryId: z.string().optional().describe("Repository ID to filter builds"), repositoryType: z.enum(["TfsGit", "GitHub", "BitbucketCloud"]).optional().describe("Type of repository to filter builds"), }, async ({ organization, project, definitions, queues, buildNumber, minTime, maxTime, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, properties, top, continuationToken, maxBuildsPerDefinition, deletedFilter, queryOrder, branchName, buildIds, repositoryId, repositoryType }) => { const connection = await connectionManager.getConnection(organization); const buildApi = await connection.getBuildApi(); // Default to a summary view if properties are not specified to avoid hitting token limits // We select key fields that are most useful for status checks const defaultProperties = [ "id", "buildNumber", "status", "result", "queueTime", "startTime", "finishTime", "url", "definition", "project", "sourceBranch", "requestedFor" ]; const selectedProperties = properties || defaultProperties; // Default top to 20 if not specified to prevent massive responses const limit = top || 20; const builds = await buildApi.getBuilds( project, definitions, queues, buildNumber, minTime ? new Date(minTime) : undefined, maxTime ? new Date(maxTime) : undefined, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, selectedProperties, limit, continuationToken, maxBuildsPerDefinition, deletedFilter, safeEnumConvert(BuildQueryOrder, queryOrder), branchName, buildIds, repositoryId, repositoryType ); // Simplify the output to reduce token usage const simplifiedBuilds = builds.map(b => ({ id: b.id, buildNumber: b.buildNumber, status: b.status, result: b.result, queueTime: b.queueTime, startTime: b.startTime, finishTime: b.finishTime, definition: b.definition ? { id: b.definition.id, name: b.definition.name } : undefined, sourceBranch: b.sourceBranch, requestedFor: b.requestedFor ? { displayName: b.requestedFor.displayName } : undefined, url: b.url })); return { content: [{ type: "text", text: JSON.stringify(simplifiedBuilds, null, 2) }], }; } );