From 84dea9a049b88b97c7f7a8b723c243f9ec383d54 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sun, 22 Feb 2026 12:42:24 +0000 Subject: [PATCH 1/2] Update GitHub MCP tools mapping and documentation to v2.0 - Add 31 new tool mappings to github_tool_to_toolset.json for tools introduced in MCP server v2.0 (copilot context tools, project tools, security advisory tools, dependabot tools, search toolset expansion, actions renamed tools, and more) - Update SKILL.md with current tool names per v2.0 JSON mapping, including legacy tool name mapping table for migration guidance - Create .github/instructions/github-mcp-server.instructions.md with comprehensive tool reference, configuration examples, authentication details, and recommended toolset rationale Co-Authored-By: Claude Sonnet 4.6 --- .../github-mcp-server.instructions.md | 390 ++++++++++++++++++ pkg/workflow/data/github_tool_to_toolset.json | 39 +- skills/github-mcp-server/SKILL.md | 219 ++++++---- 3 files changed, 566 insertions(+), 82 deletions(-) create mode 100644 .github/instructions/github-mcp-server.instructions.md diff --git a/.github/instructions/github-mcp-server.instructions.md b/.github/instructions/github-mcp-server.instructions.md new file mode 100644 index 00000000000..60016e660d0 --- /dev/null +++ b/.github/instructions/github-mcp-server.instructions.md @@ -0,0 +1,390 @@ +--- +applyTo: "**" +--- + +# GitHub MCP Server Instructions + +This document provides comprehensive guidance for using the GitHub MCP (Model Context Protocol) server in agentic workflows. It covers available tools, toolset configuration, authentication, and best practices. + +**Last Updated**: 2026-02-22 +**MCP Server Version**: 2.0 (Remote Mode) +**Total Available Tools**: 56 across 19 toolsets + +## Quick Reference + +### Default Toolsets + +When no `toolsets:` configuration is specified, the following are enabled by default: +- `context` - GitHub Copilot context and support docs +- `repos` - Repository operations (read) +- `issues` - Issue management (read) +- `pull_requests` - Pull request operations (read) + +### Configuration Examples + +```yaml +# Use defaults +tools: + github: + +# Use all toolsets +tools: + github: + toolsets: [all] + +# Custom selection +tools: + github: + toolsets: [default, actions, discussions] + +# Read-only remote mode +tools: + github: + mode: remote + read-only: true + toolsets: [repos, issues] +``` + +## Complete Tool Reference + +### context toolset +*GitHub Copilot context and support documentation. No special permissions required.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `get_copilot_space` | Get details about a specific GitHub Copilot space | `space_id` | +| `github_support_docs_search` | Search GitHub support documentation | `query` | +| `list_copilot_spaces` | List available GitHub Copilot spaces | — | + +### repos toolset +*Repository operations. Requires `contents` read permission.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `get_file_contents` | Read file or directory contents from a repository | `owner`, `repo`, `path`, `ref` | +| `get_repository_tree` | Get the file tree of a repository | `owner`, `repo`, `ref`, `recursive` | +| `list_commits` | List commits in a repository | `owner`, `repo`, `sha`, `path` | +| `get_commit` | Get details of a specific commit | `owner`, `repo`, `sha` | +| `list_branches` | List branches in a repository | `owner`, `repo` | +| `list_tags` | List tags in a repository | `owner`, `repo` | +| `get_tag` | Get details of a specific tag | `owner`, `repo`, `tag` | +| `get_latest_release` | Get the latest release for a repository | `owner`, `repo` | +| `get_release_by_tag` | Get a release by its tag name | `owner`, `repo`, `tag` | +| `list_releases` | List all releases for a repository | `owner`, `repo` | + +### issues toolset +*Issue management. Requires `issues` read/write permission.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `issue_read` | Read issue details and comments | `owner`, `repo`, `issue_number` | +| `list_issues` | List issues in a repository | `owner`, `repo`, `state`, `labels` | +| `list_issue_types` | List available issue types for a repository | `owner`, `repo` | +| `search_issues` | Search issues (also available via `search` toolset) | `query`, `owner`, `repo` | + +### pull_requests toolset +*Pull request operations. Requires `pull-requests` read/write permission.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `pull_request_read` | Read pull request details, reviews, and comments | `owner`, `repo`, `pull_number` | +| `list_pull_requests` | List pull requests in a repository | `owner`, `repo`, `state`, `base` | +| `search_pull_requests` | Search pull requests (also available via `search` toolset) | `query`, `owner`, `repo` | + +### actions toolset +*GitHub Actions workflows and CI/CD. Requires `actions` read permission.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `actions_list` | List GitHub Actions workflows and workflow runs | `owner`, `repo`, `workflow_id` | +| `actions_get` | Get details of a specific workflow run | `owner`, `repo`, `run_id` | +| `get_job_logs` | Download logs for a specific workflow job | `owner`, `repo`, `job_id` | + +### code_security toolset +*Code scanning alerts. Requires `security-events` read/write permission.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `list_code_scanning_alerts` | List code scanning alerts for a repository | `owner`, `repo`, `state`, `severity` | +| `get_code_scanning_alert` | Get details of a specific code scanning alert | `owner`, `repo`, `alert_number` | + +### dependabot toolset +*Dependabot vulnerability alerts. Requires `security-events` read permission.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `list_dependabot_alerts` | List Dependabot alerts for a repository | `owner`, `repo`, `state`, `severity` | +| `get_dependabot_alert` | Get details of a specific Dependabot alert | `owner`, `repo`, `alert_number` | + +### discussions toolset +*GitHub Discussions. Requires `discussions` read/write permission.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `list_discussions` | List discussions in a repository | `owner`, `repo`, `category_id` | +| `get_discussion` | Get details of a specific discussion | `owner`, `repo`, `discussion_number` | +| `get_discussion_comments` | Get comments for a specific discussion | `owner`, `repo`, `discussion_number` | +| `list_discussion_categories` | List discussion categories for a repository | `owner`, `repo` | + +### experiments toolset +*Experimental/preview features. May be unstable. No special permissions.* + +Currently no tools are available in this toolset. + +### gists toolset +*GitHub Gist operations. No special permissions required.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `get_gist` | Get a specific gist by ID | `gist_id` | +| `list_gists` | List gists for a user | `username` | + +### labels toolset +*Label management. Requires `issues` read/write permission.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `get_label` | Get details of a specific label | `owner`, `repo`, `name` | +| `list_label` | List labels in a repository | `owner`, `repo` | + +### notifications toolset +*User notification management. No special permissions required.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `list_notifications` | List user notifications | `all`, `participating` | +| `get_notification_details` | Get details of a specific notification | `thread_id` | + +### orgs toolset +*Organization security operations. No special permissions required.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `list_org_repository_security_advisories` | List security advisories for repositories in an organization | `org` | + +### projects toolset +*GitHub Projects (classic and new). Requires a PAT — not supported by `GITHUB_TOKEN`.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `list_projects` | List GitHub Projects for a user or organization | `owner`, `org` | +| `get_project` | Get details of a specific project | `project_id` | +| `list_project_items` | List items (issues, PRs, notes) in a project | `project_id` | +| `get_project_item` | Get a specific project item | `project_id`, `item_id` | +| `list_project_fields` | List fields defined in a project | `project_id` | +| `get_project_field` | Get a specific project field | `project_id`, `field_id` | + +### secret_protection toolset +*Secret scanning alerts. Requires `security-events` read permission.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `list_secret_scanning_alerts` | List secret scanning alerts for a repository | `owner`, `repo`, `state` | +| `get_secret_scanning_alert` | Get details of a specific secret scanning alert | `owner`, `repo`, `alert_number` | + +### security_advisories toolset +*Security advisory management. Requires `security-events` read/write permission.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `list_global_security_advisories` | List advisories from the GitHub Advisory Database | `ecosystem`, `severity`, `cve_id` | +| `get_global_security_advisory` | Get a specific global security advisory | `ghsa_id` | +| `list_repository_security_advisories` | List security advisories for a specific repository | `owner`, `repo`, `state` | + +### stargazers toolset +*Repository star information. No special permissions required.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `list_starred_repositories` | List repositories starred by a user | `username` | + +### users toolset +*User profile information. Requires additional token scopes not available via `GITHUB_TOKEN`.* + +No tools currently listed. Requires explicit PAT configuration. + +### search toolset +*Advanced GitHub search. No special permissions required.* + +| Tool | Purpose | Key Parameters | +|------|---------|----------------| +| `search_repositories` | Search for repositories | `query`, `sort`, `order` | +| `search_code` | Search code across repositories | `query`, `owner`, `repo` | +| `search_issues` | Search issues and pull requests | `query`, `sort`, `order` | +| `search_pull_requests` | Search pull requests | `query`, `sort`, `order` | +| `search_users` | Search GitHub users | `query`, `sort`, `order` | +| `search_orgs` | Search GitHub organizations | `query` | + +## Toolset Configuration Reference + +### Standard Configuration + +```yaml +tools: + github: + mode: "remote" # "remote" (default) or "local" + toolsets: [all] # or specific toolsets + read-only: false # true = read-only mode + github-token: "..." # optional custom token +``` + +### Available Toolset Values + +| Value | Description | +|-------|-------------| +| `default` | Recommended defaults: context, repos, issues, pull_requests | +| `all` | All toolsets | +| `context` | GitHub Copilot context and support | +| `repos` | Repository operations | +| `issues` | Issue management | +| `pull_requests` | Pull request operations | +| `actions` | GitHub Actions workflows | +| `code_security` | Code scanning alerts | +| `dependabot` | Dependabot alerts | +| `discussions` | GitHub Discussions | +| `experiments` | Experimental features | +| `gists` | Gist operations | +| `labels` | Label management | +| `notifications` | Notification management | +| `orgs` | Organization security | +| `projects` | GitHub Projects (requires PAT) | +| `secret_protection` | Secret scanning | +| `security_advisories` | Security advisories | +| `stargazers` | Repository stars | +| `users` | User profiles (requires PAT) | +| `search` | Advanced search | + +### Recommended Defaults Rationale + +The default toolsets (`context`, `repos`, `issues`, `pull_requests`) are chosen because: +- **`context`**: Provides Copilot space awareness and support docs search, useful across all workflows +- **`repos`**: Core repository access is needed for almost every workflow +- **`issues`**: Issue tracking is fundamental to most development workflows +- **`pull_requests`**: PR operations are essential for code review and CI workflows + +**Specialized toolsets** that should be explicitly enabled when needed: +- `actions` — For CI/CD monitoring and log analysis +- `discussions` — For community Q&A and announcement workflows +- `search` — For cross-repository search operations +- `code_security`, `dependabot`, `secret_protection` — For security audit workflows +- `security_advisories` — For advisory management +- `projects` — For project board management (requires PAT) +- `notifications` — For notification management workflows +- `labels` — For label automation +- `gists` — For gist-based workflows +- `orgs` — For organization-level security advisory listing +- `stargazers` — For star/engagement tracking +- `users` — For user profile lookups (requires PAT) +- `experiments` — For preview/experimental features + +## Authentication + +### Remote Mode (Recommended) + +``` +Authorization: Bearer +X-MCP-Readonly: true (optional, for read-only enforcement) +``` + +**Token priority** (first available): +1. `github-token:` field in workflow configuration +2. `GH_AW_GITHUB_TOKEN` secret +3. `GITHUB_TOKEN` (default Actions token) + +### Local Mode (Docker) + +Environment variables: +- `GITHUB_PERSONAL_ACCESS_TOKEN` — Required +- `GITHUB_READ_ONLY=1` — Optional read-only mode +- `GITHUB_TOOLSETS=repos,issues` — Optional toolset filter + +## Token Permissions Reference + +| Toolset | Required Permission | Notes | +|---------|--------------------|-| +| `context` | None | Public data only | +| `repos` | `contents: read` | Repository file access | +| `issues` | `issues: read` | Issue/comment access | +| `pull_requests` | `pull-requests: read` | PR access | +| `actions` | `actions: read` | Workflow logs access | +| `code_security` | `security-events: read` | Code scanning | +| `dependabot` | `security-events: read` | Dependabot alerts | +| `discussions` | `discussions: read` | Discussion access | +| `gists` | None (public) or PAT | Gist access | +| `labels` | `issues: read` | Label access | +| `notifications` | None | Auth user notifications | +| `orgs` | None | Public org data | +| `projects` | PAT required | Not supported by GITHUB_TOKEN | +| `secret_protection` | `security-events: read` | Secret scanning | +| `security_advisories` | `security-events: read` | Advisory access | +| `stargazers` | None | Public star data | +| `users` | PAT required | Not supported by GITHUB_TOKEN | +| `search` | None | Public search | + +## Important Notes and Limitations + +### Tools Not Available via GITHUB_TOKEN + +The following toolsets require a Personal Access Token (PAT) and **cannot** be used with the default `GITHUB_TOKEN`: +- `projects` — GitHub Projects require project-scope PAT +- `users` — User management requires additional OAuth scopes + +### Billing and Cost Data + +Detailed per-run billing costs are **not available** through the GitHub API with standard permissions. The `actions` toolset provides run duration and status but not cost data. Use the GitHub billing UI or require `admin:org` PAT for billing reports. + +### Write Operations + +While the JSON mapping shows `write_permissions` for many toolsets, the actual write tools (create_issue, create_pull_request, etc.) are handled through the `safe-outputs` mechanism in agentic workflows to ensure proper audit trails and permission checks. + +### Rate Limits + +- Authenticated REST API: ~5,000 requests/hour (PAT) or lower (GITHUB_TOKEN) +- GraphQL API: Complexity-based limits +- Design workflows to paginate and minimize unnecessary requests + +## Usage Examples + +### Workflow: Repository Code Review +```yaml +tools: + github: + toolsets: [repos, pull_requests, issues] +``` + +### Workflow: Security Audit +```yaml +tools: + github: + toolsets: [code_security, dependabot, secret_protection] + read-only: true +``` + +### Workflow: CI/CD Monitor +```yaml +tools: + github: + toolsets: [default, actions] +``` + +### Workflow: Community Management +```yaml +tools: + github: + toolsets: [default, discussions, labels] +``` + +### Workflow: Full Access +```yaml +tools: + github: + toolsets: [all] + github-token: "${{ secrets.CUSTOM_PAT }}" +``` + +## References + +- [GitHub MCP Server Repository](https://github.com/github/github-mcp-server) +- [Model Context Protocol Specification](https://modelcontextprotocol.io/) +- [GitHub Actions Documentation](https://docs.github.com/actions) +- [Agentic Workflows Reference](../.github/aw/github-agentic-workflows.md) diff --git a/pkg/workflow/data/github_tool_to_toolset.json b/pkg/workflow/data/github_tool_to_toolset.json index 22f305923ee..49b0d910ee5 100644 --- a/pkg/workflow/data/github_tool_to_toolset.json +++ b/pkg/workflow/data/github_tool_to_toolset.json @@ -2,10 +2,13 @@ "get_me": "users", "get_teams": "context", "get_team_members": "context", + "get_copilot_space": "context", + "github_support_docs_search": "context", + "list_copilot_spaces": "context", "get_repository": "repos", "get_file_contents": "repos", - "search_code": "repos", + "search_code": "search", "list_commits": "repos", "get_commit": "repos", "get_latest_release": "repos", @@ -14,20 +17,22 @@ "get_tag": "repos", "list_tags": "repos", "list_branches": "repos", + "get_repository_tree": "repos", "issue_read": "issues", "list_issues": "issues", "create_issue": "issues", "update_issue": "issues", - "search_issues": "issues", + "search_issues": "search", "add_reaction": "issues", "create_issue_comment": "issues", + "list_issue_types": "issues", "pull_request_read": "pull_requests", "list_pull_requests": "pull_requests", "get_pull_request": "pull_requests", "create_pull_request": "pull_requests", - "search_pull_requests": "pull_requests", + "search_pull_requests": "search", "list_workflows": "actions", "list_workflow_runs": "actions", @@ -37,33 +42,59 @@ "list_workflow_jobs": "actions", "get_job_logs": "actions", "list_workflow_run_artifacts": "actions", + "actions_get": "actions", + "actions_list": "actions", "list_code_scanning_alerts": "code_security", "get_code_scanning_alert": "code_security", "create_code_scanning_alert": "code_security", + "get_dependabot_alert": "dependabot", + "list_dependabot_alerts": "dependabot", + "list_discussions": "discussions", "create_discussion": "discussions", + "get_discussion": "discussions", + "get_discussion_comments": "discussions", + "list_discussion_categories": "discussions", "create_gist": "gists", + "get_gist": "gists", "list_gists": "gists", "get_label": "labels", + "list_label": "labels", "list_labels": "labels", "create_label": "labels", "list_notifications": "notifications", "mark_notifications_read": "notifications", + "get_notification_details": "notifications", "get_organization": "orgs", "list_organizations": "orgs", + "list_org_repository_security_advisories": "orgs", + + "get_project": "projects", + "get_project_field": "projects", + "get_project_item": "projects", + "list_project_fields": "projects", + "list_project_items": "projects", + "list_projects": "projects", "list_secret_scanning_alerts": "secret_protection", "get_secret_scanning_alert": "secret_protection", + "get_global_security_advisory": "security_advisories", + "list_global_security_advisories": "security_advisories", + "list_repository_security_advisories": "security_advisories", + + "list_starred_repositories": "stargazers", + "get_user": "users", "list_users": "users", "search_repositories": "search", - "search_users": "search" + "search_users": "search", + "search_orgs": "search" } diff --git a/skills/github-mcp-server/SKILL.md b/skills/github-mcp-server/SKILL.md index 71fa00c0064..b16b596d2e9 100644 --- a/skills/github-mcp-server/SKILL.md +++ b/skills/github-mcp-server/SKILL.md @@ -10,7 +10,7 @@ This file contains comprehensive documentation about the GitHub MCP (Model Conte **Note**: This file is automatically generated and updated by the `github-mcp-tools-report.md` workflow. Manual edits may be overwritten. -**Last Updated**: [To be filled by workflow] +**Last Updated**: 2026-02-22 ## Overview @@ -92,9 +92,9 @@ The `allowed:` pattern for listing individual GitHub tools is **not recommended ### Recommended Default Toolsets The following toolsets are enabled by default when `toolsets:` is not specified: -- `context` - User and environment context (strongly recommended) +- `context` - GitHub Copilot context and environment (includes support docs search) - `repos` - Repository management -- `issues` - Issue management +- `issues` - Issue management - `pull_requests` - Pull request operations **Note**: The `users` toolset is not included by default and must be explicitly specified if needed. @@ -103,95 +103,122 @@ The following toolsets are enabled by default when `toolsets:` is not specified: | Toolset | Description | Common Tools | |---------|-------------|--------------| -| `context` | User and environment context | `get_teams`, `get_team_members` | -| `repos` | Repository management | `get_repository`, `get_file_contents`, `search_code`, `list_commits` | -| `issues` | Issue management | `issue_read`, `list_issues`, `create_issue`, `search_issues` | -| `pull_requests` | Pull request operations | `pull_request_read`, `list_pull_requests`, `create_pull_request` | -| `actions` | GitHub Actions/CI/CD | `list_workflows`, `list_workflow_runs`, `download_workflow_run_artifact` | +| `context` | GitHub Copilot context and support | `get_copilot_space`, `list_copilot_spaces`, `github_support_docs_search` | +| `repos` | Repository management | `get_file_contents`, `get_repository_tree`, `list_commits`, `get_commit`, `list_branches` | +| `issues` | Issue management | `issue_read`, `list_issues`, `list_issue_types`, `search_issues` | +| `pull_requests` | Pull request operations | `pull_request_read`, `list_pull_requests`, `search_pull_requests` | +| `actions` | GitHub Actions/CI/CD | `actions_list`, `actions_get`, `get_job_logs` | | `code_security` | Code scanning and security | `list_code_scanning_alerts`, `get_code_scanning_alert` | -| `dependabot` | Dependency management | Dependabot alerts and updates | -| `discussions` | GitHub Discussions | `list_discussions`, `create_discussion` | +| `dependabot` | Dependency management | `list_dependabot_alerts`, `get_dependabot_alert` | +| `discussions` | GitHub Discussions | `list_discussions`, `get_discussion`, `get_discussion_comments`, `list_discussion_categories` | | `experiments` | Experimental features | Unstable/preview APIs | -| `gists` | Gist operations | `create_gist`, `list_gists` | -| `labels` | Label management | `get_label`, `list_labels`, `create_label` | -| `notifications` | Notifications | `list_notifications`, `mark_notifications_read` | -| `orgs` | Organization management | `get_organization`, `list_organizations` | -| `projects` | GitHub Projects | Project board operations | -| `secret_protection` | Secret scanning | Secret detection and management | -| `security_advisories` | Security advisories | Advisory creation and management | -| `stargazers` | Repository stars | Star-related operations | -| `users` | User profiles | `get_me`, `get_user`, `list_users` | -| `search` | Advanced search | Search across repos, code, users | +| `gists` | Gist operations | `get_gist`, `list_gists` | +| `labels` | Label management | `get_label`, `list_label` | +| `notifications` | Notifications | `list_notifications`, `get_notification_details` | +| `orgs` | Organization security advisories | `list_org_repository_security_advisories` | +| `projects` | GitHub Projects | `list_projects`, `get_project`, `list_project_items`, `get_project_field` | +| `secret_protection` | Secret scanning | `list_secret_scanning_alerts`, `get_secret_scanning_alert` | +| `security_advisories` | Security advisories | `list_global_security_advisories`, `get_global_security_advisory`, `list_repository_security_advisories` | +| `stargazers` | Repository stars | `list_starred_repositories` | +| `users` | User profiles | User-related operations (requires explicit token scopes) | +| `search` | Advanced search | `search_repositories`, `search_code`, `search_issues`, `search_pull_requests`, `search_users`, `search_orgs` | ## Available Tools by Toolset This section maps individual tools to their respective toolsets to help with migration from `allowed:` to `toolsets:`. ### Context Toolset -- `get_teams` - List teams the user belongs to -- `get_team_members` - List members of a specific team +- `get_copilot_space` - Get details about a specific GitHub Copilot space +- `list_copilot_spaces` - List available GitHub Copilot spaces +- `github_support_docs_search` - Search GitHub support documentation ### Repos Toolset -- `get_repository` - Get repository information -- `get_file_contents` - Read file contents from repository -- `search_code` - Search code across repositories +- `get_file_contents` - Read file contents from a repository +- `get_repository_tree` - Get the file tree of a repository - `list_commits` - List commits in a repository - `get_commit` - Get details of a specific commit -- `get_latest_release` - Get the latest release -- `list_releases` - List all releases +- `list_branches` - List branches in a repository +- `list_tags` - List tags in a repository +- `get_tag` - Get details of a specific tag +- `get_latest_release` - Get the latest release for a repository +- `get_release_by_tag` - Get a release by its tag name +- `list_releases` - List all releases for a repository ### Issues Toolset -- `issue_read` - Read issue details +- `issue_read` - Read issue details and comments - `list_issues` - List issues in a repository -- `create_issue` - Create a new issue -- `update_issue` - Update an existing issue -- `search_issues` - Search issues across repositories -- `add_reaction` - Add reaction to an issue or comment -- `create_issue_comment` - Add a comment to an issue +- `list_issue_types` - List available issue types for a repository +- `search_issues` - Search issues (alias; primary search is in `search` toolset) ### Pull Requests Toolset -- `pull_request_read` - Read pull request details +- `pull_request_read` - Read pull request details and reviews - `list_pull_requests` - List pull requests in a repository -- `get_pull_request` - Get details of a specific pull request -- `create_pull_request` - Create a new pull request -- `search_pull_requests` - Search pull requests across repositories +- `search_pull_requests` - Search pull requests (alias; primary search is in `search` toolset) ### Actions Toolset -- `list_workflows` - List GitHub Actions workflows -- `list_workflow_runs` - List workflow runs -- `get_workflow_run` - Get details of a specific workflow run -- `download_workflow_run_artifact` - Download workflow artifacts +- `actions_list` - List GitHub Actions workflows and runs +- `actions_get` - Get details of a specific workflow run +- `get_job_logs` - Download logs for a specific workflow job ### Code Security Toolset -- `list_code_scanning_alerts` - List code scanning alerts -- `get_code_scanning_alert` - Get details of a specific alert -- `create_code_scanning_alert` - Create a code scanning alert +- `list_code_scanning_alerts` - List code scanning alerts for a repository +- `get_code_scanning_alert` - Get details of a specific code scanning alert + +### Dependabot Toolset +- `list_dependabot_alerts` - List Dependabot alerts for a repository +- `get_dependabot_alert` - Get details of a specific Dependabot alert ### Discussions Toolset - `list_discussions` - List discussions in a repository -- `create_discussion` - Create a new discussion +- `get_discussion` - Get details of a specific discussion +- `get_discussion_comments` - Get comments for a discussion +- `list_discussion_categories` - List discussion categories for a repository + +### Gists Toolset +- `get_gist` - Get a specific gist +- `list_gists` - List gists for a user ### Labels Toolset - `get_label` - Get label details -- `list_labels` - List labels in a repository -- `create_label` - Create a new label - -### Users Toolset -- `get_me` - Get current authenticated user information -- `get_user` - Get user profile information -- `list_users` - List users +- `list_label` - List labels in a repository ### Notifications Toolset - `list_notifications` - List user notifications -- `mark_notifications_read` - Mark notifications as read +- `get_notification_details` - Get details of a specific notification -### Organizations Toolset -- `get_organization` - Get organization details -- `list_organizations` - List organizations +### Orgs Toolset +- `list_org_repository_security_advisories` - List security advisories for repositories in an organization -### Gists Toolset -- `create_gist` - Create a new gist -- `list_gists` - List user's gists +### Projects Toolset +- `list_projects` - List GitHub Projects for a user or organization +- `get_project` - Get details of a specific project +- `list_project_items` - List items in a project +- `get_project_item` - Get a specific project item +- `list_project_fields` - List fields defined in a project +- `get_project_field` - Get a specific project field + +### Secret Protection Toolset +- `list_secret_scanning_alerts` - List secret scanning alerts for a repository +- `get_secret_scanning_alert` - Get details of a specific secret scanning alert + +### Security Advisories Toolset +- `list_global_security_advisories` - List global security advisories from the GitHub Advisory Database +- `get_global_security_advisory` - Get details of a specific global security advisory +- `list_repository_security_advisories` - List security advisories for a specific repository + +### Stargazers Toolset +- `list_starred_repositories` - List repositories starred by a user + +### Users Toolset +User-related tools (requires explicit token scopes not available via `GITHUB_TOKEN`). + +### Search Toolset +- `search_repositories` - Search for repositories +- `search_code` - Search code across repositories +- `search_issues` - Search issues and pull requests +- `search_pull_requests` - Search pull requests +- `search_users` - Search GitHub users +- `search_orgs` - Search GitHub organizations ## Authentication Details @@ -229,11 +256,14 @@ The local mode uses environment variables: Ensure your GitHub token has appropriate permissions for the toolsets you're enabling: -- `repos` toolsets: Requires repository read/write permissions -- `issues` toolsets: Requires issues read/write permissions -- `pull_requests` toolsets: Requires pull requests read/write permissions -- `actions` toolsets: Requires actions read/write permissions -- `discussions` toolsets: Requires discussions read/write permissions +- `repos` toolsets: Requires repository read/write permissions (`contents`) +- `issues` toolsets: Requires issues read/write permissions (`issues`) +- `pull_requests` toolsets: Requires pull requests read/write permissions (`pull-requests`) +- `actions` toolsets: Requires actions read permissions (`actions`) +- `discussions` toolsets: Requires discussions read/write permissions (`discussions`) +- `code_security`, `dependabot`, `secret_protection`, `security_advisories`: Requires `security-events` +- `projects`: Requires a PAT - not supported by `GITHUB_TOKEN` +- `users`: Requires additional token scopes not available via `GITHUB_TOKEN` ### Remote vs Local Mode @@ -259,12 +289,10 @@ If you have existing workflows using the `allowed:` pattern, we recommend migrat tools: github: allowed: - - get_repository - get_file_contents - list_commits - list_issues - - create_issue - - update_issue + - issue_read ``` **Using `toolsets:` (recommended):** @@ -280,25 +308,57 @@ Use this table to identify which toolset contains the tools you need: | `allowed:` Tools | Migrate to `toolsets:` | |------------------|------------------------| -| `get_me` | `users` | -| `get_teams`, `get_team_members` | `context` | -| `get_repository`, `get_file_contents`, `search_code`, `list_commits` | `repos` | -| `issue_read`, `list_issues`, `create_issue`, `update_issue`, `search_issues` | `issues` | -| `pull_request_read`, `list_pull_requests`, `create_pull_request` | `pull_requests` | -| `list_workflows`, `list_workflow_runs`, `get_workflow_run` | `actions` | +| `get_copilot_space`, `list_copilot_spaces`, `github_support_docs_search` | `context` | +| `get_file_contents`, `get_repository_tree`, `list_commits`, `get_commit`, `list_branches`, `list_tags`, `get_latest_release` | `repos` | +| `issue_read`, `list_issues`, `list_issue_types` | `issues` | +| `pull_request_read`, `list_pull_requests` | `pull_requests` | +| `actions_list`, `actions_get`, `get_job_logs` | `actions` | | `list_code_scanning_alerts`, `get_code_scanning_alert` | `code_security` | -| `list_discussions`, `create_discussion` | `discussions` | -| `get_label`, `list_labels`, `create_label` | `labels` | -| `get_user`, `list_users` | `users` | +| `list_dependabot_alerts`, `get_dependabot_alert` | `dependabot` | +| `list_discussions`, `get_discussion`, `get_discussion_comments`, `list_discussion_categories` | `discussions` | +| `get_gist`, `list_gists` | `gists` | +| `get_label`, `list_label` | `labels` | +| `list_notifications`, `get_notification_details` | `notifications` | +| `list_org_repository_security_advisories` | `orgs` | +| `list_projects`, `get_project`, `list_project_items`, `get_project_field` | `projects` | +| `list_secret_scanning_alerts`, `get_secret_scanning_alert` | `secret_protection` | +| `list_global_security_advisories`, `get_global_security_advisory`, `list_repository_security_advisories` | `security_advisories` | +| `list_starred_repositories` | `stargazers` | +| `search_repositories`, `search_code`, `search_issues`, `search_pull_requests`, `search_users`, `search_orgs` | `search` | | Mixed repos/issues/PRs tools | `[default]` | | All tools | `[all]` | +### Legacy Tool Name Mapping + +Some tools were renamed between MCP server versions. Use this table when migrating from older `allowed:` configurations: + +| Legacy Tool Name | Current Toolset | Notes | +|-----------------|-----------------|-------| +| `get_teams`, `get_team_members` | `context` | Replaced by copilot space tools in v2 | +| `get_repository` | `repos` | Use `get_file_contents` or `get_repository_tree` | +| `search_code` | `search` | Moved from `repos` to `search` toolset | +| `create_issue`, `update_issue` | `issues` | Write operations via toolset | +| `add_reaction`, `create_issue_comment` | `issues` | Write operations via toolset | +| `get_pull_request`, `create_pull_request` | `pull_requests` | Write operations via toolset | +| `list_workflows`, `list_workflow_runs`, `get_workflow_run` | `actions` | Renamed to `actions_list`, `actions_get` | +| `download_workflow_run_artifact`, `get_workflow_run_usage` | `actions` | Via `actions` toolset | +| `list_workflow_jobs`, `list_workflow_run_artifacts` | `actions` | Via `actions` toolset | +| `create_code_scanning_alert` | `code_security` | Write operation via toolset | +| `create_discussion` | `discussions` | Write operation via toolset | +| `create_gist` | `gists` | Write operation via toolset | +| `list_labels`, `create_label` | `labels` | Write operations; `list_labels` → `list_label` | +| `mark_notifications_read` | `notifications` | Write operation via toolset | +| `get_organization`, `list_organizations` | `orgs` | Replaced by advisory-focused tools | +| `get_me` | `users` | Via `users` toolset | +| `get_user`, `list_users` | `users` | Via `users` toolset | +| `search_issues`, `search_pull_requests` | `search` | Moved to `search` toolset | + ### Quick Migration Steps 1. **Identify tools in use**: Review your current `allowed:` list 2. **Map to toolsets**: Use the table above to find corresponding toolsets 3. **Replace configuration**: Change `allowed:` to `toolsets:` -4. **Test**: Run `gh aw mcp inspect ` to verify tools are available +4. **Test**: Run `gh aw mcp inspect ` to verify tools are available 5. **Compile**: Run `gh aw compile` to update the lock file ## Using Allowed Pattern with Custom MCP Servers @@ -342,7 +402,7 @@ Not all GitHub data is accessible through the GitHub MCP server or the GitHub RE 1. **GitHub Actions usage reports** — Download usage reports from the GitHub billing UI (Settings → Billing → Usage) or via the billing CSV export endpoint (requires `admin:org` scope with a PAT). 2. **Billing settings UI** — Direct users to `https://github.com/organizations/{org}/settings/billing` or `https://github.com/settings/billing` for personal accounts to view cost data manually. -3. **Workflow run metadata** — Use `list_workflow_runs` and `get_workflow_run` (available via `actions` toolset) to get run duration, status, and timing — but not dollar costs. +3. **Workflow run metadata** — Use `actions_list` and `actions_get` (available via `actions` toolset) to get run duration, status, and timing — but not dollar costs. 4. **Third-party cost tracking** — Integrate with third-party CI cost tools that use pre-authorized API access. ### Cross-Organization Data Access @@ -384,6 +444,9 @@ Not all GitHub data is accessible through the GitHub MCP server or the GitHub RE **Issue**: Workflow using `allowed:` list is verbose and hard to maintain - **Solution**: Migrate to `toolsets:` configuration using the migration guide above +**Issue**: Tool name changed between versions +- **Solution**: Use the Legacy Tool Name Mapping table above to find the current toolset + ### Best Practices for Debugging 1. **Start with `[default]` toolset**: Most workflows work well with default toolsets From 49bc87988da86c1ed32e43c1e4fa9679e4dae27b Mon Sep 17 00:00:00 2001 From: Claude Code Date: Sun, 22 Feb 2026 12:48:45 +0000 Subject: [PATCH 2/2] test: Add smoke test push marker for run 22277347943 Co-Authored-By: Claude Sonnet 4.6 --- smoke-push-22277347943.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 smoke-push-22277347943.md diff --git a/smoke-push-22277347943.md b/smoke-push-22277347943.md new file mode 100644 index 00000000000..1036a64206f --- /dev/null +++ b/smoke-push-22277347943.md @@ -0,0 +1 @@ +# Smoke Test Push 22277347943