pipelines.md•17.9 kB
# Pipeline Tools
This document describes the tools available for working with Azure DevOps pipelines.
## Table of Contents
- [`list_pipelines`](#list_pipelines) - List pipelines in a project
- [`get_pipeline`](#get_pipeline) - Get details of a specific pipeline
- [`list_pipeline_runs`](#list_pipeline_runs) - List recent runs for a pipeline
- [`get_pipeline_run`](#get_pipeline_run) - Get details of a specific run (plus artifacts)
- [`download_pipeline_artifact`](#download_pipeline_artifact) - Download an artifact file as text
- [`pipeline_timeline`](#pipeline_timeline) - Retrieve the stage and job timeline for a run
- [`get_pipeline_log`](#get_pipeline_log) - Retrieve raw or JSON-formatted log content
- [`trigger_pipeline`](#trigger_pipeline) - Trigger a pipeline run
## list_pipelines
Lists pipelines in a project.
### Parameters
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | --------------------------------------------------------- |
| `projectId` | string | No | The ID or name of the project (Default: from environment) |
| `orderBy` | string | No | Order by field and direction (e.g., "createdDate desc") |
| `top` | number | No | Maximum number of pipelines to return |
### Response
Returns an array of pipeline objects:
```json
{
"count": 2,
"value": [
{
"id": 4,
"revision": 2,
"name": "Node.js build pipeline",
"folder": "\\",
"url": "https://dev.azure.com/organization/project/_apis/pipelines/4"
},
{
"id": 1,
"revision": 1,
"name": "Sample Pipeline",
"folder": "\\",
"url": "https://dev.azure.com/organization/project/_apis/pipelines/1"
}
]
}
```
### Error Handling
- Returns `AzureDevOpsResourceNotFoundError` if the project does not exist
- Returns `AzureDevOpsAuthenticationError` if authentication fails
- Returns generic error messages for other failures
### Example Usage
```javascript
// Using default project from environment
const result = await callTool('list_pipelines', {});
// Specifying project and limiting results
const limitedResult = await callTool('list_pipelines', {
projectId: 'my-project',
top: 10,
orderBy: 'name asc',
});
```
## get_pipeline
Gets details of a specific pipeline.
### Parameters
| Parameter | Type | Required | Description |
| ----------------- | ------ | -------- | ----------------------------------------------------------------- |
| `projectId` | string | No | The ID or name of the project (Default: from environment) |
| `pipelineId` | number | Yes | The numeric ID of the pipeline to retrieve |
| `pipelineVersion` | number | No | The version of the pipeline to retrieve (latest if not specified) |
### Response
Returns a pipeline object with the following structure:
```json
{
"id": 4,
"revision": 2,
"name": "Node.js build pipeline",
"folder": "\\",
"url": "https://dev.azure.com/organization/project/_apis/pipelines/4",
"_links": {
"self": {
"href": "https://dev.azure.com/organization/project/_apis/pipelines/4"
},
"web": {
"href": "https://dev.azure.com/organization/project/_build/definition?definitionId=4"
}
},
"configuration": {
"path": "azure-pipelines.yml",
"repository": {
"id": "bd0e8130-7fba-4f3b-8559-54760b6e7248",
"type": "azureReposGit"
},
"type": "yaml"
}
}
```
### Error Handling
- Returns `AzureDevOpsResourceNotFoundError` if the pipeline or project does not exist
- Returns `AzureDevOpsAuthenticationError` if authentication fails
- Returns generic error messages for other failures
### Example Usage
```javascript
// Get latest version of a pipeline
const result = await callTool('get_pipeline', {
pipelineId: 4,
});
// Get specific version of a pipeline
const versionResult = await callTool('get_pipeline', {
projectId: 'my-project',
pipelineId: 4,
pipelineVersion: 2,
});
```
## list_pipeline_runs
Lists recent runs for a given pipeline with optional filtering by branch, state, result, or time window.
### Parameters
| Parameter | Type | Required | Description |
| ------------------- | ------------ | -------- | --------------------------------------------------------------------------- |
| `projectId` | string | No | The ID or name of the project (Default: from environment) |
| `pipelineId` | number | Yes | Numeric ID of the pipeline whose runs should be returned |
| `top` | number | No | Maximum rows to return (1-100, default 50) |
| `continuationToken` | string | No | Continuation token for paging through long histories |
| `branch` | string | No | Filter runs by branch (accepts `main` or full ref like `refs/heads/main`) |
| `state` | string | No | Filter by current run state (`notStarted`, `inProgress`, `completed`, etc.) |
| `result` | string | No | Filter by final run result (`succeeded`, `failed`, `canceled`, etc.) |
| `createdFrom` | string (ISO) | No | Restrict runs created on or after this timestamp |
| `createdTo` | string (ISO) | No | Restrict runs created on or before this timestamp |
| `orderBy` | string | No | Sort order for creation date (`createdDate desc` by default) |
### Response
Returns the runs plus a continuation token when more pages are available:
```json
{
"runs": [
{
"id": 13590799,
"name": "20251001.2",
"createdDate": "2025-10-01T08:59:27.343Z",
"state": "completed",
"result": "succeeded",
"pipeline": { "id": 69847, "name": "embed-confluence-content" },
"_links": {
"web": {
"href": "https://dev.azure.com/org/project/_build/results?buildId=13590799"
}
}
}
],
"continuationToken": "eyJwYWdlIjoxfQ=="
}
```
### Error Handling
- Returns `AzureDevOpsResourceNotFoundError` if the pipeline or project does not exist
- Returns `AzureDevOpsAuthenticationError` if authentication fails
- Returns generic error messages for other failures
### Example Usage
```javascript
// Fetch the latest 10 runs on the main branch
const runs = await callTool('list_pipeline_runs', {
pipelineId: 69847,
top: 10,
branch: 'main',
});
// Continue from a previous page
const nextPage = await callTool('list_pipeline_runs', {
pipelineId: 69847,
continuationToken: runs.continuationToken,
});
```
## get_pipeline_run
Gets detailed information about a single pipeline run, including artifact listings when available.
### Parameters
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | --------------------------------------------------------------------------- |
| `projectId` | string | No | The ID or name of the project (Default: from environment) |
| `runId` | number | Yes | Numeric ID of the pipeline run |
| `pipelineId` | number | No | Optional guard to validate the run belongs to the specified pipeline |
### Response
Returns the pipeline run enriched with artifact metadata:
```json
{
"id": 13590799,
"name": "20251001.2",
"state": "completed",
"result": "succeeded",
"pipeline": { "id": 69847, "name": "embed-confluence-content" },
"createdDate": "2025-10-01T08:59:27.343Z",
"artifacts": [
{
"name": "embedding-batch",
"type": "PipelineArtifact",
"downloadUrl": "https://.../embedding-batch.zip",
"signedContentUrl": "https://.../signedContent",
"items": [
{ "path": "logs", "itemType": "folder" },
{ "path": "logs/summary.json", "itemType": "file" }
]
},
{
"name": "embedding-metrics",
"type": "Container",
"containerId": 39106000,
"rootPath": "embedding-metrics",
"items": [
{ "path": "embedding_metrics.json", "itemType": "file", "size": 2048 }
]
}
]
}
```
### Error Handling
- Returns `AzureDevOpsResourceNotFoundError` if the run or project does not exist
- Returns `AzureDevOpsResourceNotFoundError` if `pipelineId` is provided and does not match the run
- Returns `AzureDevOpsAuthenticationError` if authentication fails
- Returns generic error messages for other failures
### Example Usage
```javascript
// Inspect a run and the files it produced
const run = await callTool('get_pipeline_run', {
runId: 13590799,
});
// Guard against a run from another pipeline
await callTool('get_pipeline_run', {
pipelineId: 69847,
runId: 13590799,
});
```
## download_pipeline_artifact
Downloads a single file from a pipeline run artifact (container or pipeline artifact) and returns its textual content.
### Parameters
| Parameter | Type | Required | Description |
| -------------- | ------ | -------- | --------------------------------------------------------------------------- |
| `projectId` | string | No | The ID or name of the project (Default: from environment) |
| `runId` | number | Yes | Numeric ID of the pipeline run |
| `artifactPath` | string | Yes | Artifact name and file path (e.g., `artifact-name/path/to/file.json`) |
| `pipelineId` | number | No | Optional guard to disambiguate runs triggered by different pipelines |
### Response
Returns the file content along with artifact metadata:
```json
{
"artifact": "embedding-metrics",
"path": "embedding-metrics/embedding_metrics.json",
"content": "{\n \"status\": \"ok\"\n}"
}
```
### Error Handling
- Returns `AzureDevOpsResourceNotFoundError` if the artifact or requested file is missing
- Returns `AzureDevOpsAuthenticationError` if the artifact storage cannot be accessed
- Returns generic error messages for other failures
### Example Usage
```javascript
// Download a JSON summary generated by the run
const artifact = await callTool('download_pipeline_artifact', {
runId: 13590799,
artifactPath: 'embedding-metrics/embedding_metrics.json',
});
console.log(JSON.parse(artifact.content));
```
## pipeline_timeline
Retrieves the timeline of stages, jobs, and tasks for a pipeline run with optional filtering by state and result.
### Parameters
| Parameter | Type | Required | Description |
| ------------ | ---------------------- | -------- | ------------------------------------------------------------------------------- |
| `projectId` | string | No | The ID or name of the project (Default: from environment) |
| `runId` | number | Yes | Numeric ID of the pipeline run |
| `timelineId` | string | No | Fetch a specific timeline record (otherwise returns the default timeline) |
| `pipelineId` | number | No | Optional reference to the pipeline for documentation purposes |
| `state` | string or string array | No | Filter returned records by state (`pending`, `inProgress`, `completed`) |
| `result` | string or string array | No | Filter returned records by result (`succeeded`, `failed`, `canceled`, etc.) |
### Response
Returns the timeline records (filtered when requested):
```json
{
"id": "f9d9c210-06c7-4e53-b45f-6b661341fa7f",
"records": [
{
"id": "Stage_1",
"name": "Build",
"type": "Stage",
"state": "completed",
"result": "succeeded",
"startTime": "2025-10-01T08:59:30.123Z",
"finishTime": "2025-10-01T09:02:10.456Z"
},
{
"id": "Job_1",
"name": "Agent job",
"type": "Job",
"parentId": "Stage_1",
"state": "completed",
"result": "succeeded"
}
]
}
```
### Error Handling
- Returns `AzureDevOpsResourceNotFoundError` if the timeline or project does not exist
- Returns `AzureDevOpsAuthenticationError` if authentication fails
- Returns generic error messages for other failures
### Example Usage
```javascript
// Fetch the full timeline
const timeline = await callTool('pipeline_timeline', {
runId: 13590799,
});
// Only keep completed records
const completed = await callTool('pipeline_timeline', {
runId: 13590799,
state: 'completed',
});
```
## get_pipeline_log
Retrieves log content for a specific timeline log. Supports plain text or JSON (structured lines) formats.
### Parameters
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------------------------------------------- |
| `projectId` | string | No | The ID or name of the project (Default: from environment) |
| `runId` | number | Yes | Numeric ID of the pipeline run |
| `logId` | number | Yes | Log identifier from the timeline records |
| `format` | string | No | `plain` (default) or `json` |
| `startLine` | number | No | First line to include (useful for large logs) |
| `endLine` | number | No | Last line to include (exclusive, when paired with `startLine`) |
| `pipelineId` | number | No | Optional reference to help locate the log when working across many pipelines |
### Response
- When `format` is omitted or set to `plain`, returns a newline-delimited string:
```text
Queueing build...
Starting: Build
##[section]Starting: Initialize job
```
- When `format` is set to `json`, returns the structured log payload from Azure DevOps:
```json
[
{
"line": 1,
"stepRecordId": "Job_1",
"content": "##[section]Starting: Initialize job"
}
]
```
### Error Handling
- Returns `AzureDevOpsResourceNotFoundError` if the log or project does not exist
- Returns `AzureDevOpsAuthenticationError` if authentication fails
- Returns generic error messages for other failures
### Example Usage
```javascript
// Grab the first 200 lines of plain text
const logText = await callTool('get_pipeline_log', {
runId: 13590799,
logId: 12,
startLine: 0,
endLine: 200,
});
// Fetch the same lines as structured JSON
const logJson = await callTool('get_pipeline_log', {
runId: 13590799,
logId: 12,
format: 'json',
startLine: 0,
endLine: 200,
});
```
## trigger_pipeline
Triggers a run of a specific pipeline. Allows specifying the branch to run on and passing variables to customize the pipeline execution.
### Parameters
| Parameter | Type | Required | Description |
| -------------------- | ------ | -------- | --------------------------------------------------------------------- |
| `projectId` | string | No | The ID or name of the project (Default: from environment) |
| `pipelineId` | number | Yes | The numeric ID of the pipeline to trigger |
| `branch` | string | No | The branch to run the pipeline on (e.g., "main", "feature/my-branch") |
| `variables` | object | No | Variables to pass to the pipeline run |
| `templateParameters` | object | No | Parameters for template-based pipelines |
| `stagesToSkip` | array | No | Stages to skip in the pipeline run |
#### Variables Format
```json
{
"myVariable": {
"value": "my-value",
"isSecret": false
},
"secretVariable": {
"value": "secret-value",
"isSecret": true
}
}
```
### Response
Returns a run object with details about the triggered pipeline run:
```json
{
"id": 12345,
"name": "20230215.1",
"createdDate": "2023-02-15T10:30:00Z",
"url": "https://dev.azure.com/organization/project/_apis/pipelines/runs/12345",
"_links": {
"self": {
"href": "https://dev.azure.com/organization/project/_apis/pipelines/runs/12345"
},
"web": {
"href": "https://dev.azure.com/organization/project/_build/results?buildId=12345"
}
},
"state": 1,
"result": null,
"variables": {
"myVariable": {
"value": "my-value"
}
}
}
```
### Error Handling
- Returns `AzureDevOpsResourceNotFoundError` if the pipeline or project does not exist
- Returns `AzureDevOpsAuthenticationError` if authentication fails
- Returns generic error messages for other failures
### Example Usage
```javascript
// Trigger a pipeline on the default branch
// In this case, use default project from environment variables
const result = await callTool('trigger_pipeline', {
pipelineId: 4,
});
// Trigger a pipeline on a specific branch with variables
const runWithOptions = await callTool('trigger_pipeline', {
projectId: 'my-project',
pipelineId: 4,
branch: 'feature/my-branch',
variables: {
deployEnvironment: {
value: 'staging',
isSecret: false,
},
},
});
```