trigger_pipeline

Start a pipeline run in Azure DevOps by specifying the pipeline ID, branch, variables, and optional parameters to control execution.

Instructions

Trigger a pipeline run

Input Schema

TableJSON Schema

Name	Required	Description
`projectId`	No	The ID or name of the project (Default: MyProject)
`pipelineId`	Yes	The numeric ID of the pipeline to trigger
`branch`	No	The branch to run the pipeline on (e.g., "main", "feature/my-branch"). If left empty, the default branch will be used
`variables`	No	Variables to pass to the pipeline run
`templateParameters`	No	Parameters for template-based pipelines
`stagesToSkip`	No	Stages to skip in the pipeline run

Implementation Reference

src/features/pipelines/trigger-pipeline/feature.ts:17-101 (handler)

The core handler function that triggers a pipeline run using the Azure DevOps Pipelines API. It prepares run parameters including variables, template parameters, stages to skip, and branch resources, then calls pipelinesApi.runPipeline() and handles errors appropriately.

export async function triggerPipeline(
  connection: WebApi,
  options: TriggerPipelineOptions,
): Promise<Run> {
  try {
    const pipelinesApi = await connection.getPipelinesApi();
    const {
      projectId = defaultProject,
      pipelineId,
      branch,
      variables,
      templateParameters,
      stagesToSkip,
    } = options;

    // Prepare run parameters
    const runParameters: Record<string, unknown> = {};

    // Add variables
    if (variables) {
      runParameters.variables = variables;
    }

    // Add template parameters
    if (templateParameters) {
      runParameters.templateParameters = templateParameters;
    }

    // Add stages to skip
    if (stagesToSkip && stagesToSkip.length > 0) {
      runParameters.stagesToSkip = stagesToSkip;
    }

    // Prepare resources (including branch)
    const resources: Record<string, unknown> = branch
      ? { repositories: { self: { refName: `refs/heads/${branch}` } } }
      : {};

    // Add resources to run parameters if not empty
    if (Object.keys(resources).length > 0) {
      runParameters.resources = resources;
    }
    // Call pipeline API to run pipeline
    const result = await pipelinesApi.runPipeline(
      runParameters,
      projectId,
      pipelineId,
    );

    return result;
  } catch (error) {
    // Handle specific error types
    if (error instanceof AzureDevOpsError) {
      throw error;
    }

    // Check for specific error types and convert to appropriate Azure DevOps errors
    if (error instanceof Error) {
      if (
        error.message.includes('Authentication') ||
        error.message.includes('Unauthorized') ||
        error.message.includes('401')
      ) {
        throw new AzureDevOpsAuthenticationError(
          `Failed to authenticate: ${error.message}`,
        );
      }

      if (
        error.message.includes('not found') ||
        error.message.includes('does not exist') ||
        error.message.includes('404')
      ) {
        throw new AzureDevOpsResourceNotFoundError(
          `Pipeline or project not found: ${error.message}`,
        );
      }
    }

    // Otherwise, wrap it in a generic error
    throw new AzureDevOpsError(
      `Failed to trigger pipeline: ${error instanceof Error ? error.message : String(error)}`,
    );
  }
}

src/features/pipelines/trigger-pipeline/schema.ts:7-46 (schema)

Zod schema defining the input parameters for the trigger_pipeline tool, including projectId, pipelineId, branch, variables, templateParameters, and stagesToSkip.

export const TriggerPipelineSchema = z.object({
  // The project containing the pipeline
  projectId: z
    .string()
    .optional()
    .describe(`The ID or name of the project (Default: ${defaultProject})`),
  // The ID of the pipeline to trigger
  pipelineId: z
    .number()
    .int()
    .positive()
    .describe('The numeric ID of the pipeline to trigger'),
  // The branch to run the pipeline on
  branch: z
    .string()
    .optional()
    .describe(
      'The branch to run the pipeline on (e.g., "main", "feature/my-branch"). If left empty, the default branch will be used',
    ),
  // Variables to pass to the pipeline run
  variables: z
    .record(
      z.object({
        value: z.string(),
        isSecret: z.boolean().optional(),
      }),
    )
    .optional()
    .describe('Variables to pass to the pipeline run'),
  // Parameters for template-based pipelines
  templateParameters: z
    .record(z.string())
    .optional()
    .describe('Parameters for template-based pipelines'),
  // Stages to skip in the pipeline run
  stagesToSkip: z
    .array(z.string())
    .optional()
    .describe('Stages to skip in the pipeline run'),
});

src/features/pipelines/tool-definitions.ts:61-67 (registration)
Tool registration in the pipelinesTools array, defining the name, description, input schema, and MCP enablement.
```
  {
    name: 'trigger_pipeline',
    description: 'Trigger a pipeline run',
    inputSchema: zodToJsonSchema(TriggerPipelineSchema),
    mcp_enabled: true,
  },
];
```

src/features/pipelines/index.ts:142-151 (registration)

Dispatch handler in the pipelines request switch statement that parses arguments with TriggerPipelineSchema and calls the triggerPipeline function.

case 'trigger_pipeline': {
  const args = TriggerPipelineSchema.parse(request.params.arguments);
  const result = await triggerPipeline(connection, {
    ...args,
    projectId: args.projectId ?? defaultProject,
  });
  return {
    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
  };
}

src/features/pipelines/index.ts:56-56 (registration)
Inclusion of 'trigger_pipeline' in the isPipelinesRequest tool name check.
```
'trigger_pipeline',
```

Azure DevOps MCP Server