list-workflow-runs
Retrieve and filter workflow execution history for GitHub repositories to monitor CI/CD pipeline status and troubleshoot builds.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner | |
| repo | Yes | Repository name | |
| workflow_id | No | Workflow ID or file name | |
| branch | No | Filter by branch name | |
| status | No | Filter by run status | |
| page | No | Page number | |
| perPage | No | Items per page |
Implementation Reference
- server/index.ts:1239-1317 (registration)Tool registration including input schema (zod) and handler function that calls ActionsAPI.listWorkflowRunsserver.tool( "list-workflow-runs", { owner: z.string().min(1).describe("Repository owner"), repo: z.string().min(1).describe("Repository name"), workflow_id: z.union([z.string(), z.number()]).optional().describe("Workflow ID or file name"), branch: z.string().optional().describe("Filter by branch name"), status: z.enum(['completed', 'action_required', 'cancelled', 'failure', 'neutral', 'skipped', 'stale', 'success', 'timed_out', 'in_progress', 'queued', 'requested', 'waiting']).optional().describe("Filter by run status"), page: z.number().int().positive().optional().describe("Page number"), perPage: z.number().int().positive().optional().describe("Items per page") }, async ({ owner, repo, workflow_id, branch, status, page, perPage }) => { try { // Parameter validation if (!owner || typeof owner !== 'string' || owner.trim() === '') { return { content: [ { type: "text", text: "Repository owner is required." } ] }; } if (!repo || typeof repo !== 'string' || repo.trim() === '') { return { content: [ { type: "text", text: "Repository name is required." } ] }; } const response = await context.actions.listWorkflowRuns(owner, repo, { workflow_id, branch, status, page, per_page: perPage }); if (!response.workflow_runs || response.workflow_runs.length === 0) { return { content: [ { type: "text", text: workflow_id ? `No workflow runs found for workflow '${workflow_id}' in repository '${owner}/${repo}'.` : `No workflow runs found in repository '${owner}/${repo}'.` } ] }; } const formattedRuns = response.workflow_runs.map(formatWorkflowRun); return { content: [ { type: "text", text: `${workflow_id ? `Workflow '${workflow_id}'` : 'Workflow'} runs in repository '${owner}/${repo}' (${response.total_count}):\n\n${JSON.stringify(formattedRuns, null, 2)}` } ] }; } catch (error: any) { return { content: [ { type: "text", text: `Error listing workflow runs: ${error.message}` } ] }; } } );
- api/actions/actions.ts:55-74 (helper)ActionsAPI.listWorkflowRuns: core method that makes the GitHub API request for workflow runsasync listWorkflowRuns(owner: string, repo: string, options: { workflow_id?: number | string; actor?: string; branch?: string; event?: string; status?: 'completed' | 'action_required' | 'cancelled' | 'failure' | 'neutral' | 'skipped' | 'stale' | 'success' | 'timed_out' | 'in_progress' | 'queued' | 'requested' | 'waiting'; created?: string; page?: number; per_page?: number; } = {}): Promise<GitHubWorkflowRunListResponse> { const endpoint = options.workflow_id ? `repos/${owner}/${repo}/actions/workflows/${options.workflow_id}/runs` : `repos/${owner}/${repo}/actions/runs`; const { workflow_id, ...params } = options; return this.client.get<GitHubWorkflowRunListResponse>(endpoint, { params }); }
- server/index.ts:132-148 (helper)formatWorkflowRun: utility function to format workflow run data for user-friendly outputfunction formatWorkflowRun(run: any) { return { id: run.id, name: run.name, workflow_id: run.workflow_id, run_number: run.run_number, event: run.event, status: run.status, conclusion: run.conclusion, created_at: run.created_at, updated_at: run.updated_at, url: run.html_url, head_branch: run.head_branch, head_sha: run.head_sha, run_attempt: run.run_attempt }; }
- server/index.ts:1242-1249 (schema)Zod input schema for the list-workflow-runs tool parametersowner: z.string().min(1).describe("Repository owner"), repo: z.string().min(1).describe("Repository name"), workflow_id: z.union([z.string(), z.number()]).optional().describe("Workflow ID or file name"), branch: z.string().optional().describe("Filter by branch name"), status: z.enum(['completed', 'action_required', 'cancelled', 'failure', 'neutral', 'skipped', 'stale', 'success', 'timed_out', 'in_progress', 'queued', 'requested', 'waiting']).optional().describe("Filter by run status"), page: z.number().int().positive().optional().describe("Page number"), perPage: z.number().int().positive().optional().describe("Items per page") },