list-workflow-runs
Retrieve and filter GitHub workflow runs by status, branch, or workflow ID to monitor CI/CD pipeline execution and track build statuses.
Instructions
List workflow runs in a GitHub repository
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| branch | No | Filter by branch name | |
| owner | Yes | Repository owner | |
| page | No | Page number | |
| perPage | No | Items per page | |
| repo | Yes | Repository name | |
| status | No | Filter by run status | |
| workflow_id | No | Workflow ID or file name |
Implementation Reference
- src/tools/repository.ts:312-362 (handler)The primary handler function that parses input using ListWorkflowRunsSchema, calls GitHub Actions API to list workflow runs (either for a specific workflow or all in repo), and formats the response.
export async function listWorkflowRuns(args: unknown): Promise<any> { const { owner, repo, workflow_id, branch, status, page, perPage } = ListWorkflowRunsSchema.parse(args); const github = getGitHubApi(); return tryCatchAsync(async () => { let data; if (workflow_id) { // List runs for a specific workflow const response = await github.getOctokit().actions.listWorkflowRuns({ owner, repo, workflow_id, branch, status: status as any, page, per_page: perPage, }); data = response.data; } else { // List all workflow runs const response = await github.getOctokit().actions.listWorkflowRunsForRepo({ owner, repo, branch, status: status as any, page, per_page: perPage, }); data = response.data; } return { total_count: data.total_count, workflow_runs: data.workflow_runs.map((run) => ({ id: run.id, name: run.name, workflow_id: run.workflow_id, head_branch: run.head_branch, head_sha: run.head_sha, 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, })), }; }, 'Failed to list workflow runs'); } - src/utils/validation.ts:233-255 (schema)Zod schema for validating the input arguments to the listWorkflowRuns handler, extending OwnerRepoSchema with optional workflow_id, branch, status enum, page, and perPage.
export const ListWorkflowRunsSchema = OwnerRepoSchema.extend({ workflow_id: z.union([z.string(), z.number()]).optional(), branch: z.string().optional(), status: z .enum([ 'completed', 'action_required', 'cancelled', 'failure', 'neutral', 'skipped', 'stale', 'success', 'timed_out', 'in_progress', 'queued', 'requested', 'waiting', ]) .optional(), page: z.number().int().optional(), perPage: z.number().int().optional(), }); - src/server.ts:302-355 (registration)MCP tool registration entry in server.tools.add array, defining the tool name, description, and inputSchema matching the handler validation.
{ name: 'list-workflow-runs', description: 'List workflow runs in a GitHub repository', inputSchema: { type: 'object', properties: { owner: { type: 'string', description: 'Repository owner', }, repo: { type: 'string', description: 'Repository name', }, workflow_id: { type: ['string', 'number'], description: 'Workflow ID or file name', }, branch: { type: 'string', description: 'Filter by branch name', }, status: { type: 'string', enum: [ 'completed', 'action_required', 'cancelled', 'failure', 'neutral', 'skipped', 'stale', 'success', 'timed_out', 'in_progress', 'queued', 'requested', 'waiting', ], description: 'Filter by run status', }, page: { type: 'integer', description: 'Page number', }, perPage: { type: 'integer', description: 'Items per page', }, }, required: ['owner', 'repo'], additionalProperties: false, }, }, - src/server.ts:1184-1186 (registration)Switch case in the CallToolRequestHandler that dispatches tool calls named 'list-workflow-runs' to the listWorkflowRuns handler function.
case 'list-workflow-runs': result = await listWorkflowRuns(parsedArgs); break;