list_workflow_runs
Retrieve and filter workflow runs for a GitHub repository by owner, repo, workflow ID, actor, branch, event, status, or creation date. Supports pagination and excluding PR-triggered runs.
Instructions
List all workflow runs for a repository or specific workflow
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| actor | No | Filter by user who triggered the workflow | |
| branch | No | Filter by branch | |
| checkSuiteId | No | Filter by check suite ID | |
| created | No | Filter by creation date (YYYY-MM-DD) | |
| event | No | Filter by event type | |
| excludePullRequests | No | Exclude PR-triggered runs | |
| owner | Yes | Repository owner | |
| page | No | Page number for pagination | |
| perPage | No | Results per page (max 100) | |
| repo | Yes | Repository name | |
| status | No | Filter by status | |
| workflowId | No | The ID of the workflow or filename |
Implementation Reference
- src/tools/list-workflow-runs.ts:5-68 (handler)The handler function that executes the tool logic, fetching workflow runs from GitHub API using Octokit based on provided filters.const handleListWorkflowRuns: ToolHandler = async (args, octokit: Octokit) => { const { owner, repo, workflowId, actor, branch, event, status, created, excludePullRequests, checkSuiteId, page, perPage } = args; try { const params: any = { owner, repo, page, per_page: perPage }; if (actor) params.actor = actor; if (branch) params.branch = branch; if (event) params.event = event; if (status) params.status = status; if (created) params.created = created; if (excludePullRequests !== undefined) params.exclude_pull_requests = excludePullRequests; if (checkSuiteId) params.check_suite_id = checkSuiteId; let response; if (workflowId) { response = await octokit.rest.actions.listWorkflowRuns({ ...params, workflow_id: workflowId }); } else { response = await octokit.rest.actions.listWorkflowRunsForRepo(params); } return { total_count: response.data.total_count, workflow_runs: response.data.workflow_runs.map(run => ({ id: run.id, name: run.name, head_branch: run.head_branch, head_sha: run.head_sha, status: run.status, conclusion: run.conclusion, workflow_id: run.workflow_id, created_at: run.created_at, updated_at: run.updated_at, run_number: run.run_number, event: run.event, actor: run.actor, html_url: run.html_url })) }; } catch (error: any) { throw new WorkflowError(`Failed to list workflow runs: ${error.message}`, error.response?.data); } };
- src/tools/tool-definitions.ts:74-104 (schema)The tool definition object containing the name, description, and inputSchema for validating tool inputs.{ name: "list_workflow_runs", description: "List all workflow runs for a repository or specific workflow", inputSchema: { type: "object", properties: { owner: { type: "string", description: "Repository owner" }, repo: { type: "string", description: "Repository name" }, workflowId: { oneOf: [ { type: "string" }, { type: "number" } ], description: "The ID of the workflow or filename" }, actor: { type: "string", description: "Filter by user who triggered the workflow" }, branch: { type: "string", description: "Filter by branch" }, event: { type: "string", description: "Filter by event type" }, status: { type: "string", enum: ["completed", "action_required", "cancelled", "failure", "neutral", "skipped", "stale", "success", "timed_out", "in_progress", "queued", "requested", "waiting"], description: "Filter by status" }, created: { type: "string", description: "Filter by creation date (YYYY-MM-DD)" }, excludePullRequests: { type: "boolean", description: "Exclude PR-triggered runs" }, checkSuiteId: { type: "number", description: "Filter by check suite ID" }, page: { type: "number", description: "Page number for pagination" }, perPage: { type: "number", description: "Results per page (max 100)" } }, required: ["owner", "repo"] }
- src/tools/index.ts:14-25 (registration)Registration of all tool handlers in a map, mapping 'list_workflow_runs' to its handler function.export const toolHandlers: Record<string, ToolHandler> = { create_workflow: handleCreateWorkflow, list_workflows: handleListWorkflows, get_workflow: handleGetWorkflow, get_workflow_usage: handleGetWorkflowUsage, list_workflow_runs: handleListWorkflowRuns, get_workflow_run: handleGetWorkflowRun, get_workflow_run_jobs: handleGetWorkflowRunJobs, trigger_workflow: handleTriggerWorkflow, cancel_workflow_run: handleCancelWorkflowRun, rerun_workflow: handleRerunWorkflow, };
- src/tools/index.ts:7-7 (registration)Import of the handler function for list_workflow_runs.import handleListWorkflowRuns from './list-workflow-runs.js';