GitHub Actions MCP Server

Instructions

Implementation Reference

• src/tools/trigger-workflow.ts:5-46 (handler)

  The main ToolHandler function implementing the trigger_workflow tool. It resolves the workflow ID by name if it's a string matching a workflow name, lists workflows if necessary, and dispatches the workflow using Octokit's createWorkflowDispatch.

  const handleTriggerWorkflow: ToolHandler = async (args, octokit: Octokit) => {
    const { owner, repo, workflowId, ref, inputs } = args;
    
    try {
      let workflow_id = workflowId;
      
      if (typeof workflowId === 'string' && (workflowId.includes(' ') || /^[A-Z]/.test(workflowId))) {
        const workflows = await octokit.rest.actions.listRepoWorkflows({
          owner,
          repo
        });
        
        // Find the workflow by name
        const matchedWorkflow = workflows.data.workflows.find(w => 
          w.name.toLowerCase() === workflowId.toLowerCase() || 
          w.name === workflowId
        );
        
        if (matchedWorkflow) {
          workflow_id = matchedWorkflow.id;
        } else {
          throw new WorkflowError(`Workflow with name "${workflowId}" not found. Make sure the name matches exactly as defined in the workflow file.`);
        }
      }
      
      const response = await octokit.rest.actions.createWorkflowDispatch({
        owner,
        repo,
        workflow_id,
        ref,
        inputs
      });
  
      return {
        success: true,
        message: "Workflow triggered successfully",
        status: response.status
      };
    } catch (error: any) {
      throw new WorkflowError(`Failed to trigger workflow: ${error.message}`, error.response?.data);
    }
  };

• src/tools/tool-definitions.ts:139-159 (schema)

  The input schema definition for the trigger_workflow tool, specifying parameters like owner, repo, workflowId (string or number, supports name resolution), ref, and optional inputs.

  {
    name: "trigger_workflow",
    description: "Trigger a workflow run",
    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, filename, or display name as defined in the workflow file's 'name:' field"
        },
        ref: { type: "string", description: "The reference to run the workflow on (branch, tag, or SHA)" },
        inputs: { type: "object", description: "Input parameters for the workflow" }
      },
      required: ["owner", "repo", "workflowId", "ref"]
    }
  },

• src/tools/index.ts:14-25 (registration)

  Registration of all tool handlers in the toolHandlers map, including trigger_workflow mapped 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,
  };