list_workflow_runs
Retrieve GitHub Actions workflow runs by filtering criteria like status, branch, or actor to monitor execution history and analyze performance.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner (username or organization) | |
| repo | Yes | Repository name | |
| workflowId | No | The ID of the workflow or filename (string or number) | |
| actor | No | Returns someone's workflow runs. Use the login for the user | |
| branch | No | Returns workflow runs associated with a branch | |
| event | No | Returns workflow runs triggered by the event | |
| status | No | Returns workflow runs with the check run status | |
| created | No | Returns workflow runs created within date range (YYYY-MM-DD) | |
| excludePullRequests | No | If true, pull requests are omitted from the response | |
| checkSuiteId | No | Returns workflow runs with the check_suite_id | |
| page | No | Page number for pagination | |
| perPage | No | Results per page (max 100) |
Implementation Reference
- src/operations/actions.ts:138-178 (handler)The main handler function that executes the tool logic: validates inputs, constructs GitHub API URL, fetches workflow runs, and parses response using WorkflowRunsSchema.export async function listWorkflowRuns( owner: string, repo: string, options: { workflowId?: string | number, actor?: string, branch?: string, event?: string, status?: string, created?: string, excludePullRequests?: boolean, checkSuiteId?: number, page?: number, perPage?: number } = {} ) { owner = validateOwnerName(owner); repo = validateRepositoryName(repo); let url; if (options.workflowId) { url = `https://api.github.com/repos/${owner}/${repo}/actions/workflows/${options.workflowId}/runs`; } else { url = `https://api.github.com/repos/${owner}/${repo}/actions/runs`; } url = buildUrl(url, { actor: options.actor, branch: options.branch, event: options.event, status: options.status, created: options.created, exclude_pull_requests: options.excludePullRequests ? "true" : undefined, check_suite_id: options.checkSuiteId, page: options.page, per_page: options.perPage }); const response = await githubRequest(url); return WorkflowRunsSchema.parse(response); }
- src/operations/actions.ts:35-48 (schema)Zod schema defining input parameters and validation for the list_workflow_runs tool.export const ListWorkflowRunsSchema = z.object({ owner: z.string().describe("Repository owner (username or organization)"), repo: z.string().describe("Repository name"), workflowId: z.string().optional().describe("The ID of the workflow or filename (string or number)"), actor: z.string().optional().describe("Returns someone's workflow runs. Use the login for the user"), branch: z.string().optional().describe("Returns workflow runs associated with a branch"), event: z.string().optional().describe("Returns workflow runs triggered by the event"), status: z.enum(['completed', 'action_required', 'cancelled', 'failure', 'neutral', 'skipped', 'stale', 'success', 'timed_out', 'in_progress', 'queued', 'requested', 'waiting', 'pending']).optional().describe("Returns workflow runs with the check run status"), created: z.string().optional().describe("Returns workflow runs created within date range (YYYY-MM-DD)"), excludePullRequests: z.boolean().optional().describe("If true, pull requests are omitted from the response"), checkSuiteId: z.number().optional().describe("Returns workflow runs with the check_suite_id"), page: z.number().optional().describe("Page number for pagination"), perPage: z.number().optional().describe("Results per page (max 100)"), });
- src/index.ts:177-185 (registration)MCP server tool registration for 'list_workflow_runs', providing schema and wrapper handler that delegates to the main implementation.server.tool( "list_workflow_runs", actions.ListWorkflowRunsSchema.shape, async (request: any) => { const { owner, repo, workflowId, ...options } = request; const result = await actions.listWorkflowRuns(owner, repo, { workflowId, ...options }); return { content: [{ type: "text", text: JSON.stringify(result) }] }; } );