Actions & Workflows
Relevant source files
The following files were used as context for generating this wiki page:
The Actions & Workflows module provides a robust interface for interacting with GitHub Actions through the Model Context Protocol (MCP). It enables agents and automated tools to discover, trigger, monitor, and debug CI/CD processes within a GitHub repository. The system encompasses tools for listing workflows, managing execution runs, and retrieving detailed diagnostic logs.
This module is designed to bridge the gap between high-level development goals and the underlying automation infrastructure. By exposing these capabilities as MCP tools, the server allows AI assistants to perform complex tasks like monitoring build status after a pull request or automatically retrieving failure logs to suggest fixes.
Sources: pkg/github/actions.go:1-25, pkg/github/workflow_prompts.go:1-15
Architecture and Tool Design
The module is built around a collection of functional tools that wrap the GitHub Actions REST API. Each tool follows a consistent pattern: defining an MCP tool schema (name, description, and input parameters) and a corresponding handler function that executes the logic using a GitHub client.
Core Components
- Workflow Discovery: Tools to identify available automation files and their configurations.
- Run Management: Capabilities to trigger new runs (via
workflow_dispatch), cancel active runs, or re-run failed jobs. - Observability: Specialized tools for fetching metadata, usage metrics, and log content.
- Guided Workflows: Pre-defined prompts that orchestrate multiple tool calls into a logical developer workflow.
Sources: pkg/github/actions.go:27-150, cmd/github-mcp-server/generate_docs.go:150-200
Tool Execution Flow
The following diagram illustrates how a request to run a workflow is processed by the server.
The server supports triggering workflows by either their numeric Database ID or their YAML filename (e.g., main.yml), providing flexibility for different automation contexts.
Sources: pkg/github/actions.go:152-210, pkg/github/actions_test.go:150-200
Workflow Run Operations
Once a workflow is triggered, it creates a "Run." The module provides several tools to manage the lifecycle of these runs and inspect their outcomes.
Run Management Tools
| Tool Name | Purpose | Key Parameters |
|---|---|---|
list_workflow_runs | Filter and list history of runs | workflow_id, status, actor, event |
get_workflow_run | Get detailed state of one run | run_id |
rerun_workflow_run | Re-execute an entire run | run_id |
rerun_failed_jobs | Re-execute only failing parts | run_id |
cancel_workflow_run | Stop an active execution | run_id |
Sources: pkg/github/actions.go:85-150, pkg/github/actions.go:650-750
Diagnostics and Log Handling
Retrieving logs is a critical but potentially expensive operation. The system implements optimized strategies for log access to prevent memory exhaustion and excessive bandwidth usage.
Log Retrieval Strategies
- Full Archive:
get_workflow_run_logsprovides a URL to a ZIP archive containing all logs for every job in a run. This is recommended for comprehensive offline analysis. - Targeted Job Logs:
get_job_logscan return the URL for a single job or retrieve the actual text content directly. - Smart Failure Debugging: The
get_job_logstool supports afailed_onlyflag, which automatically discovers failed jobs in a run and retrieves their logs in one request.
Memory-Efficient Streaming
For direct log content retrieval, the server utilizes a Ring Buffer implementation. This allows the server to process very large log files while only keeping the last N lines (controlled by tail_lines) in memory, significantly reducing the memory footprint compared to reading the entire file.
Sources: pkg/github/actions.go:580-610, pkg/github/actions_test.go:1000-1050
Guided Workflow Prompts
Beyond individual tools, the module includes "Prompts" which are pre-configured sets of instructions and tool-use patterns for common developer tasks.
Issue-to-Fix Workflow
The IssueToFixWorkflow prompt provides a guided path for creating an issue and immediately assigning a coding agent to resolve it.
Arguments:
owner: Repository owner (Required)repo: Repository name (Required)title: Issue title (Required)description: Detailed problem description (Required)
This prompt sets up a multi-step conversation context where the AI assistant is instructed to:
- Create the issue with labels and assignees.
- Coordinate with Copilot coding agents.
- Monitor the resulting Pull Request.
Sources: pkg/github/workflow_prompts.go:15-70
Summary of Configuration
The Actions & Workflows tools are part of the standard repos and actions toolsets. They default to page-based pagination (30 items per page) and require standard GitHub repository permissions (read for listing, write for triggering/canceling).
Sources: cmd/github-mcp-server/generate_docs.go:80-120, pkg/github/actions.go:40-60