GitHub Actions MCP Server

Instructions

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';