feat: add GitHub Actions tools for workflow management

[gabornyergesX]

Add GitHub Actions tools for workflow management

Overview

This PR implements comprehensive GitHub Actions support for the MCP server, adding 14 new tools that enable complete workflow and CI/CD management through the GitHub Actions API.

New Tools Added

output.mp4

Workflow Management (Read-only)

• list_workflows - List all workflows in a repository
• list_workflow_runs - List workflow runs for a specific workflow with filtering options
• get_workflow_run - Get detailed information about a specific workflow run
• get_workflow_run_logs - Download logs for a workflow run
• get_workflow_run_usage - Get usage metrics and billing information for workflow runs

Job Management (Read-only)

• list_workflow_jobs - List jobs for a specific workflow run
• get_job_logs - Download logs for a specific workflow job

Artifact Management (Read-only)

• list_workflow_run_artifacts - List artifacts generated by a workflow run
• download_workflow_run_artifact - Get download URLs for workflow artifacts

Workflow Operations (Write)

• run_workflow - Trigger workflows via workflow_dispatch events
• rerun_workflow_run - Re-run entire workflow runs
• rerun_failed_jobs - Re-run only failed jobs in a workflow run
• cancel_workflow_run - Cancel running workflows

Administrative (Destructive)

• delete_workflow_run_logs - Delete workflow run logs (marked as destructive)

Key Features

✅ Complete CI/CD Workflow Support - Covers the full lifecycle from triggering workflows to managing artifacts
✅ Proper Permission Classification - Tools are correctly categorized as read-only, write, or destructive operations
✅ Comprehensive Parameter Validation - All tools include proper input validation and error handling
✅ Rich Metadata - Each tool includes detailed descriptions and parameter documentation
✅ Test Coverage - Full test suite with 50+ test cases covering all scenarios
✅ Documentation - Updated README with detailed tool descriptions and usage examples

Implementation Details

• Architecture: Follows existing MCP server patterns and conventions
• Error Handling: Consistent error responses with meaningful messages
• Pagination: Supports GitHub API pagination for list operations
• Filtering: Includes advanced filtering options (by status, actor, branch, event, etc.)
• Security: Proper handling of GitHub tokens and permissions

Testing

• Added comprehensive test suite in actions_test.go
• 50 test cases covering all tools and edge cases
• Mocked GitHub API responses for reliable testing
• All tests passing with proper error handling validation

Breaking Changes

None - this is purely additive functionality.

Closes

Closes #268 - Add support for Actions APIs

Usage Example

# List workflows in a repository  
echo '{"tool":"list_workflows","arguments":{"owner":"github","repo":"github-mcp-server"}}' | github-mcp-server

# Trigger a workflow
echo '{"tool":"run_workflow","arguments":{"owner":"github","repo":"github-mcp-server","workflow_file":"ci.yml","ref":"main"}}' | github-mcp-server

[atxtechbro]

🚀 Excellent work @gabornyergesX! This is exactly what the community has been asking for.

I've tested this implementation in my fork and it's incredibly comprehensive:

• 14 new tools covering the complete GitHub Actions lifecycle
• Excellent test coverage with 50+ test cases
• Perfect integration with existing MCP server patterns
• Proper security annotations (read-only, write, destructive)
• Great documentation updates

This addresses issue #268 perfectly and goes above and beyond the original request. The code quality is exceptional - well done! 👏

Looking forward to seeing this merged so the whole community can benefit from these powerful CI/CD automation capabilities.

[SamMorrowDrums]

This looks very comprehensive. Thank you for putting this together. I hope I can review soon.

One preliminary question:

Is there strong motivation for allowing an agent to delete logs? I am hesitant to allow agents the ability to cover their tracks after executing something malicious.

The security implications of this PR something I will need to consider. I really do want to land it though.

[atxtechbro]

💡 Enhancement Suggestion: Efficient Failed Job Logs

Great work on this comprehensive GitHub Actions implementation! After testing it, I noticed an opportunity to make it even more efficient for a common debugging use case.

🎯 Problem

Currently, to get logs for failed jobs, users must either:

1. Use get_workflow_run_logs - Downloads ALL logs (high token usage)
2. Manually combine list_workflow_jobs + get_job_logs - Multiple steps

This doesn't match the efficiency of gh run view --log-failed.

💡 Proposed Enhancement

Instead of adding a new tool, enhance the existing get_job_logs tool with optional parameters:

// Enhanced parameters for get_job_logs
mcp.WithNumber("run_id", mcp.Description("Workflow run ID (required when using failed_only)")),
mcp.WithBoolean("failed_only", mcp.Description("When true, gets logs for all failed jobs in run_id")),
mcp.WithBoolean("return_content", mcp.Description("Returns actual log content instead of URLs")),

🔧 Usage Examples

# Original usage (unchanged)
get_job_logs --job_id=12345

# New: Get failed job logs efficiently  
get_job_logs --run_id=67890 --failed_only=true --return_content=true

✅ Benefits

• Token efficient - Only processes failed jobs
• Content delivery - Returns actual logs, not URLs (like gh CLI)
• Backward compatible - No breaking changes
• Single tool - No tool proliferation

This would make the Actions toolset perfect for real-world debugging workflows!

I've created a detailed proposal in my fork: https://github.com/atxtechbro/github-mcp-server/blob/enhance/get-job-logs-failed-only/ENHANCEMENT_PROPOSAL.md

What do you think about this approach? Happy to help implement it if you're interested! 🚀

[gabornyergesX]

This looks very comprehensive. Thank you for putting this together. I hope I can review soon.

One preliminary question:

Is there strong motivation for allowing an agent to delete logs? I am hesitant to allow agents the ability to cover their tracks after executing something malicious.

The security implications of this PR something I will need to consider. I really do want to land it though.

I did not have strong motivation for that just added as an extra.
My original issue was not able to debug pipeline logs with the agent and wanted to automise.
I can remove from the PR if you decide security implications is too high.

I think delete_workflow_run_logs tool has appropriate security measures:

1. ✅ Properly marked as destructive with DestructiveHint: true
2. ✅ Full audit trail via GitHub's native audit logging
3. ✅ Requires proper permissions (actions:write scope)
4. ✅ Legitimate use cases (storage management, compliance retention policies)

Let me know how to proceed.
Thanks.

[gabornyergesX]

💡 Enhancement Suggestion: Efficient Failed Job Logs

Great work on this comprehensive GitHub Actions implementation! After testing it, I noticed an opportunity to make it even more efficient for a common debugging use case.

🎯 Problem

Currently, to get logs for failed jobs, users must either:

1. Use get_workflow_run_logs - Downloads ALL logs (high token usage)
2. Manually combine list_workflow_jobs + get_job_logs - Multiple steps

This doesn't match the efficiency of gh run view --log-failed.

💡 Proposed Enhancement

Instead of adding a new tool, enhance the existing get_job_logs tool with optional parameters:

// Enhanced parameters for get_job_logs
mcp.WithNumber("run_id", mcp.Description("Workflow run ID (required when using failed_only)")),
mcp.WithBoolean("failed_only", mcp.Description("When true, gets logs for all failed jobs in run_id")),
mcp.WithBoolean("return_content", mcp.Description("Returns actual log content instead of URLs")),

🔧 Usage Examples

# Original usage (unchanged)
get_job_logs --job_id=12345

# New: Get failed job logs efficiently  
get_job_logs --run_id=67890 --failed_only=true --return_content=true

✅ Benefits

• Token efficient - Only processes failed jobs
• Content delivery - Returns actual logs, not URLs (like gh CLI)
• Backward compatible - No breaking changes
• Single tool - No tool proliferation

This would make the Actions toolset perfect for real-world debugging workflows!

I've created a detailed proposal in my fork: https://github.com/atxtechbro/github-mcp-server/blob/enhance/get-job-logs-failed-only/ENHANCEMENT_PROPOSAL.md

What do you think about this approach? Happy to help implement it if you're interested! 🚀

should i remove get_workflow_run_logs completly?

15ca4b7