list_workflow_runs
Retrieve and filter workflow runs for a GitHub repository by branch, status, event, or user, enabling efficient monitoring and management of CI/CD pipelines.
Instructions
List all workflow runs for a repository or a specific workflow
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| actor | No | Returns someone's workflow runs. Use the login for the user | |
| branch | No | Returns workflow runs associated with a branch | |
| checkSuiteId | No | Returns workflow runs with the check_suite_id | |
| created | No | Returns workflow runs created within date range (YYYY-MM-DD) | |
| event | No | Returns workflow runs triggered by the event | |
| excludePullRequests | No | If true, pull requests are omitted from the response | |
| owner | Yes | Repository owner (username or organization) | |
| page | No | Page number for pagination | |
| perPage | No | Results per page (max 100) | |
| repo | Yes | Repository name | |
| status | No | Returns workflow runs with the check run status | |
| workflowId | No | The ID of the workflow or filename |
Implementation Reference
- src/operations/actions.ts:138-178 (handler)The handler function that executes the tool logic: validates inputs, constructs GitHub API URL for workflow runs, fetches data, and parses with 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 the 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:178-184 (registration)Registration of the list_workflow_runs tool in the MCP server using server.tool(), providing schema and handler wrapper."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) }] }; }