GitHub Actions MCP Server

Instructions

Implementation Reference

• src/tools/create-workflow.ts:5-62 (handler)

  The main handler function that implements the create_workflow tool. It generates YAML content for a GitHub Actions workflow based on input args and uses Octokit to create or update the file in the repository.

  const handleCreateWorkflow: ToolHandler = async (args, octokit: Octokit) => {
    const { owner, repo, path, name, on: triggerEvents, jobs, branch = "main", commitMessage = "Add GitHub Actions workflow" } = args;
    
    // Create workflow YAML content
    let modifiedTriggerEvents = { ...triggerEvents };
    if (!modifiedTriggerEvents) {
      modifiedTriggerEvents = {};
    }
    
    // Add workflow_dispatch if not already present
    if (!modifiedTriggerEvents.workflow_dispatch) {
      modifiedTriggerEvents.workflow_dispatch = {};
    }
    
    const formattedTriggerEvents = JSON.stringify(modifiedTriggerEvents, null, 2).replace(/"/g, '');
    
    const yamlContent = `name: ${name}
  
  on: ${formattedTriggerEvents}
  
  jobs:
  ${Object.entries(jobs || {}).map(([jobName, jobConfig]: [string, any]) => {
    return `  ${jobName}:
      runs-on: ${jobConfig['runs-on'] || 'ubuntu-latest'}
  ${jobConfig.steps ? '    steps:' : ''}
  ${jobConfig.steps ? jobConfig.steps.map((step: any, index: number) => {
    let stepYaml = `      - name: ${step.name || `Step ${index + 1}`}`;
    if (step.uses) stepYaml += `\n        uses: ${step.uses}`;
    if (step.run) stepYaml += `\n        run: ${step.run}`;
    if (step.with) stepYaml += `\n        with:\n${Object.entries(step.with || {}).map(([key, value]) => `          ${key}: ${value}`).join('\n')}`;
    if (step.env) stepYaml += `\n        env:\n${Object.entries(step.env || {}).map(([key, value]) => `          ${key}: ${value}`).join('\n')}`;
    return stepYaml;
  }).join('\n') : ''}`;
  }).join('\n\n')}`;
  
    try {
      const response = await octokit.rest.repos.createOrUpdateFileContents({
        owner,
        repo,
        path,
        message: commitMessage,
        content: Buffer.from(yamlContent).toString('base64'),
        branch
      });
  
      return {
        success: true,
        message: "Workflow created successfully",
        data: {
          path,
          sha: response.data.content?.sha,
          url: response.data.content?.html_url
        }
      };
    } catch (error: any) {
      throw new WorkflowError(`Failed to create workflow: ${error.message}`, error.response?.data);
    }
  };

• src/tools/tool-definitions.ts:5-21 (schema)

  The input schema and metadata definition for the create_workflow tool, specifying properties, descriptions, and required fields.

    name: "create_workflow",
    description: "Create a new GitHub Actions workflow file",
    inputSchema: {
      type: "object",
      properties: {
        owner: { type: "string", description: "Repository owner" },
        repo: { type: "string", description: "Repository name" },
        path: { type: "string", description: "Path for the workflow file (e.g., '.github/workflows/ci.yml')" },
        name: { type: "string", description: "Workflow name - should be descriptive and related to the workflow's purpose" },
        on: { type: "object", description: "Trigger events (e.g., {push: {branches: ['main']}, pull_request: {}})" },
        jobs: { type: "object", description: "Jobs configuration" },
        branch: { type: "string", description: "Branch to create the workflow on", default: "main" },
        commitMessage: { type: "string", description: "Commit message", default: "Add GitHub Actions workflow" }
      },
      required: ["owner", "repo", "path", "name", "on", "jobs"]
    }
  },

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

  Registration of all tool handlers, including create_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,
  };