[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6AD623Z58P272NDV95RPZ7K":3,"skill-same:01M6AD623Z58P272NDV95RPZ7K":67},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":26,"publishedAt":38,"linkOnly":39,"markdownContent":40,"markdownBody":41,"frontMatter":42,"refName":43,"commitSha":44,"skillDirectory":45,"forksCount":46,"repositoryHtmlUrl":47,"repositoryHomepageUrl":48,"ownerHtmlUrl":49,"ownerBlogUrl":50,"ownerDescription":51,"updatedAt":52,"install":53,"resources":66},"01M6AD623Z58P272NDV95RPZ7K","github-mcp-server",null,"Reference for GitHub MCP server tools, methods, and usage patterns.","github\u002Fgh-aw","github","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F9919?v=4","01M6AC83DS133TPXFSP1DHNCC6","GitHub","01M6AD3VCZ4WKQSFSRTPN7N9DN",5636,"MIT","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fgithub-mcp-server\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[27,9,28,29,30,31,32,33,34,35,36,37],"MCP","mcp server","server","github mcp server","github mcp","Tools","reference","methods","patterns","usage","for","2026-11-10 10:12:30",false,"---\nname: github-mcp-server\ndescription: Reference for GitHub MCP server tools, methods, and usage patterns.\n---\n\n\n# GitHub MCP Server Documentation\n\nThis file documents the GitHub MCP (Model Context Protocol) server, including tools and configuration options.\n\n**Note**: This file is automatically generated and updated by the `github-mcp-tools-report.md` workflow. Manual edits may be overwritten.\n\n**Last Updated**: [To be filled by workflow]\n\n## Overview\n\nThe GitHub MCP server provides AI agents with programmatic access to GitHub's API through the Model Context Protocol. It supports two modes of operation:\n\n### Local Mode (Docker-based)\n- Runs as a Docker container on the GitHub Actions runner\n- Uses `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable for authentication\n- Configurable toolsets via `GITHUB_TOOLSETS` environment variable\n- Supports read-only mode via `GITHUB_READ_ONLY` environment variable\n\n### Remote Mode (Hosted)\n- Connects to hosted GitHub MCP server at `https:\u002F\u002Fapi.githubcopilot.com\u002Fmcp\u002F`\n- Uses Bearer token authentication in HTTP headers\n- Supports read-only mode via `X-MCP-Readonly` header\n- No Docker container required\n\n## Configuration\n\n### Basic Configuration\n\n**Local Mode (Docker)**:\n```yaml\ntools:\n  github:\n    mode: \"local\"\n    toolsets: [default]  # or [repos, issues, pull_requests]\n```\n\n**Remote Mode (Hosted)**:\n```yaml\ntools:\n  github:\n    mode: \"remote\"\n    toolsets: [default]  # or [repos, issues, pull_requests]\n```\n\n### Read-Only Mode\n\nTo restrict the GitHub MCP server to read-only operations:\n\n```yaml\ntools:\n  github:\n    mode: \"remote\"\n    read-only: true\n    toolsets: [repos, issues]\n```\n\n### Custom Authentication\n\nUse a custom GitHub token instead of the default:\n\n```yaml\ntools:\n  github:\n    mode: \"remote\"\n    github-token: \"${{ secrets.CUSTOM_GITHUB_PAT }}\"\n    toolsets: [repos, issues]\n```\n\n## Available Toolsets\n\nThe GitHub MCP server organizes tools into logical toolsets. You can enable specific toolsets, use `[default]` for the recommended defaults, or use `[all]` to enable everything.\n\n:::note[Why Use Toolsets?]\nThe `allowed:` pattern for listing individual GitHub tools is **not recommended for new workflows**. Individual tool names may change between GitHub MCP server versions, but toolsets provide a stable API. Always use `toolsets:` instead. See [Migration from Allowed to Toolsets](#migration-from-allowed-to-toolsets) for guidance on updating existing workflows.\n:::\n\n:::tip[Best Practice]\n**Always use `toolsets:` for GitHub tools.** Toolsets provide:\n- **Stability**: Tool names may change between MCP server versions, but toolsets remain stable\n- **Better organization**: Clear groupings of related functionality\n- **Complete functionality**: Get all related tools automatically\n- **Reduced verbosity**: Cleaner configuration\n- **Future-proof**: New tools are automatically included as they're added\n:::\n\n### Recommended Default Toolsets\n\nThe following toolsets are enabled by default when `toolsets:` is not specified:\n- `context` - User and environment context (strongly recommended)\n- `repos` - Repository management\n- `issues` - Issue management  \n- `pull_requests` - Pull request operations\n\n**Note**: The `users` toolset is not included by default and must be explicitly specified if needed.\n\n### All Available Toolsets\n\n| Toolset | Description | Common Tools |\n|---------|-------------|--------------|\n| `context` | User and environment context | `get_teams`, `get_team_members` |\n| `repos` | Repository management | `get_repository`, `get_file_contents`, `search_code`, `list_commits` |\n| `issues` | Issue management | `issue_read`, `list_issues`, `create_issue`, `search_issues` |\n| `pull_requests` | Pull request operations | `pull_request_read`, `list_pull_requests`, `create_pull_request` |\n| `actions` | GitHub Actions\u002FCI\u002FCD | `list_workflows`, `list_workflow_runs`, `download_workflow_run_artifact` |\n| `code_security` | Code scanning and security | `list_code_scanning_alerts` ⚠️ (always include `state: open` and `severity: critical,high`), `get_code_scanning_alert` |\n| `dependabot` | Dependency management | Dependabot alerts and updates |\n| `discussions` | GitHub Discussions | `list_discussions`, `create_discussion` |\n| `experiments` | Experimental features | Unstable\u002Fpreview APIs |\n| `gists` | Gist operations | `create_gist`, `list_gists` |\n| `labels` | Label management | `get_label`, `list_labels`, `create_label` |\n| `notifications` | Notifications | `list_notifications`, `mark_notifications_read` |\n| `orgs` | Organization management | `get_organization`, `list_organizations` |\n| `projects` | GitHub Projects | Project board operations |\n| `secret_protection` | Secret scanning | Secret detection and management |\n| `security_advisories` | Security advisories | Advisory creation and management |\n| `stargazers` | Repository stars | Star-related operations |\n| `users` | User profiles | `get_me` ⚠️ (see note below), `get_user`, `list_users` |\n| `search` | Advanced search | Search across repos, code, users |\n\n:::caution[`get_me` returns 403 under the integration token]\n`get_me` is **not recommended** in agentic workflows. It returns HTTP 403 when called under the GitHub Actions integration token (which is the default in all gh-aw runs). Do **not** call `get_me` to determine the agent's identity.\n\n**Canonical identity source**: The `\u003Cgithub-context>` block is injected at the start of every workflow prompt and contains `actor`, `repository`, `run_id`, and other context values. Always read identity from there.\n:::\n\n## Available Tools by Toolset\n\nThis section maps individual tools to their respective toolsets to help with migration from `allowed:` to `toolsets:`.\n\n### Context Toolset\n- `get_teams` - List teams the user belongs to\n- `get_team_members` - List members of a specific team\n\n### Repos Toolset\n- `get_repository` - Get repository information\n- `get_file_contents` - Read file contents from repository\n- `search_code` - Search code across repositories\n- `list_commits` - List commits in a repository\n- `get_commit` - Get details of a specific commit\n- `get_latest_release` - Get the latest release\n- `list_releases` - List all releases\n\n### Issues Toolset\n- `issue_read` - Read issue details\n- `list_issues` - List issues in a repository\n- `create_issue` - Create a new issue\n- `update_issue` - Update an existing issue\n- `search_issues` - Search issues across repositories\n- `add_reaction` - Add reaction to an issue or comment\n- `create_issue_comment` - Add a comment to an issue\n\n### Pull Requests Toolset\n- `pull_request_read` - Read pull request details\n- `list_pull_requests` - List pull requests in a repository\n- `get_pull_request` - Get details of a specific pull request\n- `create_pull_request` - Create a new pull request\n- `search_pull_requests` - Search pull requests across repositories\n\nWhen invoking `list_pull_requests` from workflow prompts\u002Ftemplates:\n- Default to a small page size (`perPage: 10` unless a smaller\u002Flarger value is justified).\n- On GitHub MCP server ≥ 1.6.0 with the `fields_param` feature (enabled automatically in Insiders mode), pass `fields: [number, title, state, html_url]` (or whichever top-level fields you need) to reduce response size. The same `fields` parameter is available on `list_issues`, `search_issues`, `search_pull_requests`, `list_commits`, `list_releases`, and `search_code`. For `get_file_contents`, `fields` only reduces directory listings; use `fields: [name, type, size, path]` to check file metadata before deciding whether to read a file.\n- Before using `get_file_contents` on a file, list its parent directory with `fields: [name, type, size, path]`. If the file is large or you only need a header\u002Fsection, use a bounded excerpt such as a raw file URL with an HTTP range or another available ranged-read tool instead of fetching the whole file.\n- On older servers, request `minimal_output: true` when the installed MCP server exposes that input (minimal output trims non-essential nested fields such as large `head`\u002F`base` payloads).\n- Confirm parameter support in the method schema from `mcp list-tools` or the tool docs for your server version.\n\n### Actions Toolset\n- `list_workflows` - List GitHub Actions workflows\n- `list_workflow_runs` - List workflow runs\n- `get_workflow_run` - Get details of a specific workflow run\n- `download_workflow_run_artifact` - Download workflow artifacts\n\n### Code Security Toolset\n- `list_code_scanning_alerts` - List code scanning alerts\n- `get_code_scanning_alert` - Get details of a specific alert\n- `create_code_scanning_alert` - Create a code scanning alert\n\nWhen invoking `list_code_scanning_alerts` from workflow prompts\u002Ftemplates, always include `state: open` and `severity: critical,high` to bound the response size and avoid oversized payloads.\n\n### Discussions Toolset\n- `list_discussions` - List discussions in a repository\n- `create_discussion` - Create a new discussion\n\n### Labels Toolset\n- `get_label` - Get label details\n- `list_labels` - List labels in a repository\n- `create_label` - Create a new label\n\n### Users Toolset\n- `get_me` - ⚠️ **Not recommended** — returns HTTP 403 under the integration token. Use the `\u003Cgithub-context>` block (provided at the start of every prompt) to read your identity: `actor`, `repository`, `run_id`, etc.\n- `get_user` - Get user profile information\n- `list_users` - List users\n\n### Notifications Toolset\n- `list_notifications` - List user notifications\n- `mark_notifications_read` - Mark notifications as read\n\n### Organizations Toolset\n- `get_organization` - Get organization details\n- `list_organizations` - List organizations\n\n### Gists Toolset\n- `create_gist` - Create a new gist\n- `list_gists` - List user's gists\n\n## Authentication Details\n\n### Remote Mode Authentication\n\nThe remote mode uses Bearer token authentication:\n\n**Headers**:\n- `Authorization: Bearer \u003Ctoken>` - Required for authentication\n- `X-MCP-Readonly: true` - Optional, enables read-only mode\n\n**Token Source**:\n- Default: `${{ secrets.GH_AW_GITHUB_TOKEN }}` or `${{ secrets.GITHUB_TOKEN }}`\n- Custom: Configure via `github-token` field\n\n### Local Mode Authentication\n\nThe local mode uses environment variables:\n\n**Environment Variables**:\n- `GITHUB_PERSONAL_ACCESS_TOKEN` - Required for authentication\n- `GITHUB_READ_ONLY=1` - Optional, enables read-only mode\n- `GITHUB_TOOLSETS=\u003Ccomma-separated-list>` - Optional, specifies enabled toolsets\n\n## Best Practices\n\n### Toolset Selection\n\n1. **Start with defaults**: For most workflows, the recommended default toolsets provide sufficient functionality\n2. **Enable specific toolsets**: Only enable additional toolsets when you need their specific functionality\n3. **Security consideration**: Be mindful of write operations - consider using read-only mode when possible\n4. **Performance**: Using fewer toolsets reduces initialization time and memory usage\n\n### Token Permissions\n\nEnsure your GitHub token has appropriate permissions for the toolsets you're enabling:\n\n- `repos` toolsets: Requires repository read\u002Fwrite permissions\n- `issues` toolsets: Requires issues read\u002Fwrite permissions\n- `pull_requests` toolsets: Requires pull requests read\u002Fwrite permissions\n- `actions` toolsets: Requires actions read\u002Fwrite permissions\n- `discussions` toolsets: Requires discussions read\u002Fwrite permissions\n\n### Remote vs Local Mode\n\n**Use Remote Mode when**:\n- You want faster initialization (no Docker container to start)\n- You're running in a GitHub Actions environment with internet access\n- You want to use the latest version without specifying Docker image tags\n\n**Use Local Mode when**:\n- You need a specific version of the MCP server\n- You want to use custom arguments\n- You're running in an environment without internet access\n- You want to test with a local build of the MCP server\n\n## Migration from Allowed to Toolsets\n\nIf you have existing workflows using the `allowed:` pattern, we recommend migrating to `toolsets:` for better maintainability and stability. Individual tool names may change between MCP server versions, but toolsets provide a stable API that won't break your workflows.\n\n### Migration Examples\n\n**Using `allowed:` (not recommended):**\n```yaml\ntools:\n  github:\n    allowed:\n      - get_repository\n      - get_file_contents\n      - list_commits\n      - list_issues\n      - create_issue\n      - update_issue\n```\n\n**Using `toolsets:` (recommended):**\n```yaml\ntools:\n  github:\n    toolsets: [repos, issues]\n```\n\n### Tool-to-Toolset Mapping\n\nUse this table to identify which toolset contains the tools you need:\n\n| `allowed:` Tools | Migrate to `toolsets:` |\n|------------------|------------------------|\n| `get_me` ⚠️ (not recommended — returns 403; use `\u003Cgithub-context>` instead) | `users` |\n| `get_teams`, `get_team_members` | `context` |\n| `get_repository`, `get_file_contents`, `search_code`, `list_commits` | `repos` |\n| `issue_read`, `list_issues`, `create_issue`, `update_issue`, `search_issues` | `issues` |\n| `pull_request_read`, `list_pull_requests`, `create_pull_request` | `pull_requests` |\n| `list_workflows`, `list_workflow_runs`, `get_workflow_run` | `actions` |\n| `list_code_scanning_alerts` ⚠️ (always include `state: open` and `severity: critical,high`), `get_code_scanning_alert` | `code_security` |\n| `list_discussions`, `create_discussion` | `discussions` |\n| `get_label`, `list_labels`, `create_label` | `labels` |\n| `get_user`, `list_users` | `users` |\n| Mixed repos\u002Fissues\u002FPRs tools | `[default]` |\n| All tools | `[all]` |\n\n### Quick Migration Steps\n\n1. **Identify tools in use**: Review your current `allowed:` list\n2. **Map to toolsets**: Use the table above to find corresponding toolsets\n3. **Replace configuration**: Change `allowed:` to `toolsets:`\n4. **Test**: Run `gh aw mcp inspect \u003Cworkflow>` to verify tools are available\n5. **Compile**: Run `gh aw compile` to update the lock file\n\n## Using Allowed Pattern with Custom MCP Servers\n\n:::note[When to Use Allowed]\nThe `allowed:` pattern is appropriate for:\n- Custom MCP servers (non-GitHub)\n- Gradual migration of existing workflows\n- Fine-grained restriction of specific tools within a toolset\n\nFor GitHub tools, always use `toolsets:` instead of `allowed:`.\n:::\n\nThe `allowed:` field can still be used to restrict tools for custom MCP servers:\n\n```yaml\nmcp-servers:\n  notion:\n    container: \"mcp\u002Fnotion\"\n    allowed: [\"search_pages\", \"get_page\"]  # Fine for custom MCP servers\n```\n\nFor GitHub tools, `allowed:` can be combined with `toolsets:` to further restrict access, but this pattern is not recommended for new workflows.\n\n## GitHub API Limitations\n\nNot all GitHub data is accessible through the GitHub MCP server or the GitHub REST API. Be aware of these limitations when designing workflows to avoid silent failures or incomplete results at runtime.\n\n### Billing and Cost Data\n\n**❌ Not available via standard API permissions:**\n\n- **Detailed per-run cost data** — GitHub Actions does not expose per-workflow-run billing costs through the REST API. There is no endpoint to retrieve the exact cost of a specific workflow run.\n- **Actions billing summary** — Billing endpoints (e.g., `\u002Forgs\u002F{org}\u002Fsettings\u002Fbilling\u002Factions`) require `admin:org` scope, which is **not** granted by `actions:read` or the default `GITHUB_TOKEN`.\n\n**⚠️ When suggesting billing\u002Fcost workflows, always note:**\n\n> Detailed GitHub Actions billing and cost data is not accessible through the standard GitHub API with `actions:read` permissions. Workflows that attempt to read per-run cost data or billing summaries will fail silently or return empty results unless an `admin:org`-scoped personal access token is explicitly configured.\n\n**✅ Alternatives for cost reporting:**\n\n1. **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).\n2. **Billing settings UI** — Direct users to `https:\u002F\u002Fgithub.com\u002Forganizations\u002F{org}\u002Fsettings\u002Fbilling` or `https:\u002F\u002Fgithub.com\u002Fsettings\u002Fbilling` for personal accounts to view cost data manually.\n3. **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.\n4. **Third-party cost tracking** — Integrate with third-party CI cost tools that use pre-authorized API access.\n\n### Cross-Organization Data Access\n\n**❌ Not available without explicit authorization:**\n\n- Workflows can only access data from repositories and organizations that the configured GitHub token has been granted access to.\n- Cross-organization repository reads require a PAT or GitHub App token with access to the target org — the default `GITHUB_TOKEN` is scoped to the current repository's organization only.\n- Organization membership and team data from *other* organizations is not accessible without explicit `read:org` permissions on those organizations.\n\n### Organization Membership and Private Data\n\n**❌ Requires additional scopes:**\n\n- **Organization member lists** — Reading private organization membership requires `read:org` scope; the default `GITHUB_TOKEN` only exposes public membership.\n- **Private repository contents** — Only accessible if the token has explicit repository access.\n- **Secret values** — GitHub Secrets are write-only through the API; their values cannot be read back after creation.\n\n### Rate Limits\n\n**⚠️ Be aware of API rate limits:**\n\n- The GitHub REST API enforces rate limits (typically 5,000 requests\u002Fhour for authenticated requests with a PAT, lower for `GITHUB_TOKEN`).\n- Workflows that perform bulk data collection (e.g., listing all workflow runs across many repositories) may hit rate limits. Design workflows to paginate carefully and avoid unnecessary requests.\n- GraphQL API has separate rate limits based on query complexity.\n\n## Troubleshooting\n\n### Common Issues\n\n**Issue**: Tool not found or not available\n- **Solution**: Check if you're using `allowed:` to restrict tools. Consider using `toolsets:` instead to get all related tools.\n- **Verify**: Run `gh aw mcp inspect \u003Cworkflow-name>` to see which tools are actually available.\n\n**Issue**: Missing functionality after specifying toolset\n- **Cause**: Using a too-narrow toolset that doesn't include all needed tools\n- **Solution**: Either add additional toolsets (e.g., `toolsets: [default, actions]`) or use `[all]` for full access\n\n**Issue**: Workflow using `allowed:` list is verbose and hard to maintain\n- **Solution**: Migrate to `toolsets:` configuration using the migration guide above\n\n### Best Practices for Debugging\n\n1. **Start with `[default]` toolset**: Most workflows work well with default toolsets\n2. **Add specific toolsets as needed**: Incrementally add toolsets like `actions`, `discussions`, etc.\n3. **Use `gh aw mcp inspect`**: Verify which tools are actually available\n4. **Check tool-to-toolset mapping**: Reference the tables above to find the right toolset\n\n## References\n\n- [GitHub MCP Server Repository](https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgithub-mcp-server)\n- [Model Context Protocol Specification](https:\u002F\u002Fmodelcontextprotocol.io\u002F)\n- [GitHub Actions Documentation](https:\u002F\u002Fdocs.github.com\u002Factions)\n","# GitHub MCP Server Documentation\n\nThis file documents the GitHub MCP (Model Context Protocol) server, including tools and configuration options.\n\n**Note**: This file is automatically generated and updated by the `github-mcp-tools-report.md` workflow. Manual edits may be overwritten.\n\n**Last Updated**: [To be filled by workflow]\n\n## Overview\n\nThe GitHub MCP server provides AI agents with programmatic access to GitHub's API through the Model Context Protocol. It supports two modes of operation:\n\n### Local Mode (Docker-based)\n- Runs as a Docker container on the GitHub Actions runner\n- Uses `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable for authentication\n- Configurable toolsets via `GITHUB_TOOLSETS` environment variable\n- Supports read-only mode via `GITHUB_READ_ONLY` environment variable\n\n### Remote Mode (Hosted)\n- Connects to hosted GitHub MCP server at `https:\u002F\u002Fapi.githubcopilot.com\u002Fmcp\u002F`\n- Uses Bearer token authentication in HTTP headers\n- Supports read-only mode via `X-MCP-Readonly` header\n- No Docker container required\n\n## Configuration\n\n### Basic Configuration\n\n**Local Mode (Docker)**:\n```yaml\ntools:\n  github:\n    mode: \"local\"\n    toolsets: [default]  # or [repos, issues, pull_requests]\n```\n\n**Remote Mode (Hosted)**:\n```yaml\ntools:\n  github:\n    mode: \"remote\"\n    toolsets: [default]  # or [repos, issues, pull_requests]\n```\n\n### Read-Only Mode\n\nTo restrict the GitHub MCP server to read-only operations:\n\n```yaml\ntools:\n  github:\n    mode: \"remote\"\n    read-only: true\n    toolsets: [repos, issues]\n```\n\n### Custom Authentication\n\nUse a custom GitHub token instead of the default:\n\n```yaml\ntools:\n  github:\n    mode: \"remote\"\n    github-token: \"${{ secrets.CUSTOM_GITHUB_PAT }}\"\n    toolsets: [repos, issues]\n```\n\n## Available Toolsets\n\nThe GitHub MCP server organizes tools into logical toolsets. You can enable specific toolsets, use `[default]` for the recommended defaults, or use `[all]` to enable everything.\n\n:::note[Why Use Toolsets?]\nThe `allowed:` pattern for listing individual GitHub tools is **not recommended for new workflows**. Individual tool names may change between GitHub MCP server versions, but toolsets provide a stable API. Always use `toolsets:` instead. See [Migration from Allowed to Toolsets](#migration-from-allowed-to-toolsets) for guidance on updating existing workflows.\n:::\n\n:::tip[Best Practice]\n**Always use `toolsets:` for GitHub tools.** Toolsets provide:\n- **Stability**: Tool names may change between MCP server versions, but toolsets remain stable\n- **Better organization**: Clear groupings of related functionality\n- **Complete functionality**: Get all related tools automatically\n- **Reduced verbosity**: Cleaner configuration\n- **Future-proof**: New tools are automatically included as they're added\n:::\n\n### Recommended Default Toolsets\n\nThe following toolsets are enabled by default when `toolsets:` is not specified:\n- `context` - User and environment context (strongly recommended)\n- `repos` - Repository management\n- `issues` - Issue management  \n- `pull_requests` - Pull request operations\n\n**Note**: The `users` toolset is not included by default and must be explicitly specified if needed.\n\n### All Available Toolsets\n\n| Toolset | Description | Common Tools |\n|---------|-------------|--------------|\n| `context` | User and environment context | `get_teams`, `get_team_members` |\n| `repos` | Repository management | `get_repository`, `get_file_contents`, `search_code`, `list_commits` |\n| `issues` | Issue management | `issue_read`, `list_issues`, `create_issue`, `search_issues` |\n| `pull_requests` | Pull request operations | `pull_request_read`, `list_pull_requests`, `create_pull_request` |\n| `actions` | GitHub Actions\u002FCI\u002FCD | `list_workflows`, `list_workflow_runs`, `download_workflow_run_artifact` |\n| `code_security` | Code scanning and security | `list_code_scanning_alerts` ⚠️ (always include `state: open` and `severity: critical,high`), `get_code_scanning_alert` |\n| `dependabot` | Dependency management | Dependabot alerts and updates |\n| `discussions` | GitHub Discussions | `list_discussions`, `create_discussion` |\n| `experiments` | Experimental features | Unstable\u002Fpreview APIs |\n| `gists` | Gist operations | `create_gist`, `list_gists` |\n| `labels` | Label management | `get_label`, `list_labels`, `create_label` |\n| `notifications` | Notifications | `list_notifications`, `mark_notifications_read` |\n| `orgs` | Organization management | `get_organization`, `list_organizations` |\n| `projects` | GitHub Projects | Project board operations |\n| `secret_protection` | Secret scanning | Secret detection and management |\n| `security_advisories` | Security advisories | Advisory creation and management |\n| `stargazers` | Repository stars | Star-related operations |\n| `users` | User profiles | `get_me` ⚠️ (see note below), `get_user`, `list_users` |\n| `search` | Advanced search | Search across repos, code, users |\n\n:::caution[`get_me` returns 403 under the integration token]\n`get_me` is **not recommended** in agentic workflows. It returns HTTP 403 when called under the GitHub Actions integration token (which is the default in all gh-aw runs). Do **not** call `get_me` to determine the agent's identity.\n\n**Canonical identity source**: The `\u003Cgithub-context>` block is injected at the start of every workflow prompt and contains `actor`, `repository`, `run_id`, and other context values. Always read identity from there.\n:::\n\n## Available Tools by Toolset\n\nThis section maps individual tools to their respective toolsets to help with migration from `allowed:` to `toolsets:`.\n\n### Context Toolset\n- `get_teams` - List teams the user belongs to\n- `get_team_members` - List members of a specific team\n\n### Repos Toolset\n- `get_repository` - Get repository information\n- `get_file_contents` - Read file contents from repository\n- `search_code` - Search code across repositories\n- `list_commits` - List commits in a repository\n- `get_commit` - Get details of a specific commit\n- `get_latest_release` - Get the latest release\n- `list_releases` - List all releases\n\n### Issues Toolset\n- `issue_read` - Read issue details\n- `list_issues` - List issues in a repository\n- `create_issue` - Create a new issue\n- `update_issue` - Update an existing issue\n- `search_issues` - Search issues across repositories\n- `add_reaction` - Add reaction to an issue or comment\n- `create_issue_comment` - Add a comment to an issue\n\n### Pull Requests Toolset\n- `pull_request_read` - Read pull request details\n- `list_pull_requests` - List pull requests in a repository\n- `get_pull_request` - Get details of a specific pull request\n- `create_pull_request` - Create a new pull request\n- `search_pull_requests` - Search pull requests across repositories\n\nWhen invoking `list_pull_requests` from workflow prompts\u002Ftemplates:\n- Default to a small page size (`perPage: 10` unless a smaller\u002Flarger value is justified).\n- On GitHub MCP server ≥ 1.6.0 with the `fields_param` feature (enabled automatically in Insiders mode), pass `fields: [number, title, state, html_url]` (or whichever top-level fields you need) to reduce response size. The same `fields` parameter is available on `list_issues`, `search_issues`, `search_pull_requests`, `list_commits`, `list_releases`, and `search_code`. For `get_file_contents`, `fields` only reduces directory listings; use `fields: [name, type, size, path]` to check file metadata before deciding whether to read a file.\n- Before using `get_file_contents` on a file, list its parent directory with `fields: [name, type, size, path]`. If the file is large or you only need a header\u002Fsection, use a bounded excerpt such as a raw file URL with an HTTP range or another available ranged-read tool instead of fetching the whole file.\n- On older servers, request `minimal_output: true` when the installed MCP server exposes that input (minimal output trims non-essential nested fields such as large `head`\u002F`base` payloads).\n- Confirm parameter support in the method schema from `mcp list-tools` or the tool docs for your server version.\n\n### Actions Toolset\n- `list_workflows` - List GitHub Actions workflows\n- `list_workflow_runs` - List workflow runs\n- `get_workflow_run` - Get details of a specific workflow run\n- `download_workflow_run_artifact` - Download workflow artifacts\n\n### Code Security Toolset\n- `list_code_scanning_alerts` - List code scanning alerts\n- `get_code_scanning_alert` - Get details of a specific alert\n- `create_code_scanning_alert` - Create a code scanning alert\n\nWhen invoking `list_code_scanning_alerts` from workflow prompts\u002Ftemplates, always include `state: open` and `severity: critical,high` to bound the response size and avoid oversized payloads.\n\n### Discussions Toolset\n- `list_discussions` - List discussions in a repository\n- `create_discussion` - Create a new discussion\n\n### Labels Toolset\n- `get_label` - Get label details\n- `list_labels` - List labels in a repository\n- `create_label` - Create a new label\n\n### Users Toolset\n- `get_me` - ⚠️ **Not recommended** — returns HTTP 403 under the integration token. Use the `\u003Cgithub-context>` block (provided at the start of every prompt) to read your identity: `actor`, `repository`, `run_id`, etc.\n- `get_user` - Get user profile information\n- `list_users` - List users\n\n### Notifications Toolset\n- `list_notifications` - List user notifications\n- `mark_notifications_read` - Mark notifications as read\n\n### Organizations Toolset\n- `get_organization` - Get organization details\n- `list_organizations` - List organizations\n\n### Gists Toolset\n- `create_gist` - Create a new gist\n- `list_gists` - List user's gists\n\n## Authentication Details\n\n### Remote Mode Authentication\n\nThe remote mode uses Bearer token authentication:\n\n**Headers**:\n- `Authorization: Bearer \u003Ctoken>` - Required for authentication\n- `X-MCP-Readonly: true` - Optional, enables read-only mode\n\n**Token Source**:\n- Default: `${{ secrets.GH_AW_GITHUB_TOKEN }}` or `${{ secrets.GITHUB_TOKEN }}`\n- Custom: Configure via `github-token` field\n\n### Local Mode Authentication\n\nThe local mode uses environment variables:\n\n**Environment Variables**:\n- `GITHUB_PERSONAL_ACCESS_TOKEN` - Required for authentication\n- `GITHUB_READ_ONLY=1` - Optional, enables read-only mode\n- `GITHUB_TOOLSETS=\u003Ccomma-separated-list>` - Optional, specifies enabled toolsets\n\n## Best Practices\n\n### Toolset Selection\n\n1. **Start with defaults**: For most workflows, the recommended default toolsets provide sufficient functionality\n2. **Enable specific toolsets**: Only enable additional toolsets when you need their specific functionality\n3. **Security consideration**: Be mindful of write operations - consider using read-only mode when possible\n4. **Performance**: Using fewer toolsets reduces initialization time and memory usage\n\n### Token Permissions\n\nEnsure your GitHub token has appropriate permissions for the toolsets you're enabling:\n\n- `repos` toolsets: Requires repository read\u002Fwrite permissions\n- `issues` toolsets: Requires issues read\u002Fwrite permissions\n- `pull_requests` toolsets: Requires pull requests read\u002Fwrite permissions\n- `actions` toolsets: Requires actions read\u002Fwrite permissions\n- `discussions` toolsets: Requires discussions read\u002Fwrite permissions\n\n### Remote vs Local Mode\n\n**Use Remote Mode when**:\n- You want faster initialization (no Docker container to start)\n- You're running in a GitHub Actions environment with internet access\n- You want to use the latest version without specifying Docker image tags\n\n**Use Local Mode when**:\n- You need a specific version of the MCP server\n- You want to use custom arguments\n- You're running in an environment without internet access\n- You want to test with a local build of the MCP server\n\n## Migration from Allowed to Toolsets\n\nIf you have existing workflows using the `allowed:` pattern, we recommend migrating to `toolsets:` for better maintainability and stability. Individual tool names may change between MCP server versions, but toolsets provide a stable API that won't break your workflows.\n\n### Migration Examples\n\n**Using `allowed:` (not recommended):**\n```yaml\ntools:\n  github:\n    allowed:\n      - get_repository\n      - get_file_contents\n      - list_commits\n      - list_issues\n      - create_issue\n      - update_issue\n```\n\n**Using `toolsets:` (recommended):**\n```yaml\ntools:\n  github:\n    toolsets: [repos, issues]\n```\n\n### Tool-to-Toolset Mapping\n\nUse this table to identify which toolset contains the tools you need:\n\n| `allowed:` Tools | Migrate to `toolsets:` |\n|------------------|------------------------|\n| `get_me` ⚠️ (not recommended — returns 403; use `\u003Cgithub-context>` instead) | `users` |\n| `get_teams`, `get_team_members` | `context` |\n| `get_repository`, `get_file_contents`, `search_code`, `list_commits` | `repos` |\n| `issue_read`, `list_issues`, `create_issue`, `update_issue`, `search_issues` | `issues` |\n| `pull_request_read`, `list_pull_requests`, `create_pull_request` | `pull_requests` |\n| `list_workflows`, `list_workflow_runs`, `get_workflow_run` | `actions` |\n| `list_code_scanning_alerts` ⚠️ (always include `state: open` and `severity: critical,high`), `get_code_scanning_alert` | `code_security` |\n| `list_discussions`, `create_discussion` | `discussions` |\n| `get_label`, `list_labels`, `create_label` | `labels` |\n| `get_user`, `list_users` | `users` |\n| Mixed repos\u002Fissues\u002FPRs tools | `[default]` |\n| All tools | `[all]` |\n\n### Quick Migration Steps\n\n1. **Identify tools in use**: Review your current `allowed:` list\n2. **Map to toolsets**: Use the table above to find corresponding toolsets\n3. **Replace configuration**: Change `allowed:` to `toolsets:`\n4. **Test**: Run `gh aw mcp inspect \u003Cworkflow>` to verify tools are available\n5. **Compile**: Run `gh aw compile` to update the lock file\n\n## Using Allowed Pattern with Custom MCP Servers\n\n:::note[When to Use Allowed]\nThe `allowed:` pattern is appropriate for:\n- Custom MCP servers (non-GitHub)\n- Gradual migration of existing workflows\n- Fine-grained restriction of specific tools within a toolset\n\nFor GitHub tools, always use `toolsets:` instead of `allowed:`.\n:::\n\nThe `allowed:` field can still be used to restrict tools for custom MCP servers:\n\n```yaml\nmcp-servers:\n  notion:\n    container: \"mcp\u002Fnotion\"\n    allowed: [\"search_pages\", \"get_page\"]  # Fine for custom MCP servers\n```\n\nFor GitHub tools, `allowed:` can be combined with `toolsets:` to further restrict access, but this pattern is not recommended for new workflows.\n\n## GitHub API Limitations\n\nNot all GitHub data is accessible through the GitHub MCP server or the GitHub REST API. Be aware of these limitations when designing workflows to avoid silent failures or incomplete results at runtime.\n\n### Billing and Cost Data\n\n**❌ Not available via standard API permissions:**\n\n- **Detailed per-run cost data** — GitHub Actions does not expose per-workflow-run billing costs through the REST API. There is no endpoint to retrieve the exact cost of a specific workflow run.\n- **Actions billing summary** — Billing endpoints (e.g., `\u002Forgs\u002F{org}\u002Fsettings\u002Fbilling\u002Factions`) require `admin:org` scope, which is **not** granted by `actions:read` or the default `GITHUB_TOKEN`.\n\n**⚠️ When suggesting billing\u002Fcost workflows, always note:**\n\n> Detailed GitHub Actions billing and cost data is not accessible through the standard GitHub API with `actions:read` permissions. Workflows that attempt to read per-run cost data or billing summaries will fail silently or return empty results unless an `admin:org`-scoped personal access token is explicitly configured.\n\n**✅ Alternatives for cost reporting:**\n\n1. **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).\n2. **Billing settings UI** — Direct users to `https:\u002F\u002Fgithub.com\u002Forganizations\u002F{org}\u002Fsettings\u002Fbilling` or `https:\u002F\u002Fgithub.com\u002Fsettings\u002Fbilling` for personal accounts to view cost data manually.\n3. **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.\n4. **Third-party cost tracking** — Integrate with third-party CI cost tools that use pre-authorized API access.\n\n### Cross-Organization Data Access\n\n**❌ Not available without explicit authorization:**\n\n- Workflows can only access data from repositories and organizations that the configured GitHub token has been granted access to.\n- Cross-organization repository reads require a PAT or GitHub App token with access to the target org — the default `GITHUB_TOKEN` is scoped to the current repository's organization only.\n- Organization membership and team data from *other* organizations is not accessible without explicit `read:org` permissions on those organizations.\n\n### Organization Membership and Private Data\n\n**❌ Requires additional scopes:**\n\n- **Organization member lists** — Reading private organization membership requires `read:org` scope; the default `GITHUB_TOKEN` only exposes public membership.\n- **Private repository contents** — Only accessible if the token has explicit repository access.\n- **Secret values** — GitHub Secrets are write-only through the API; their values cannot be read back after creation.\n\n### Rate Limits\n\n**⚠️ Be aware of API rate limits:**\n\n- The GitHub REST API enforces rate limits (typically 5,000 requests\u002Fhour for authenticated requests with a PAT, lower for `GITHUB_TOKEN`).\n- Workflows that perform bulk data collection (e.g., listing all workflow runs across many repositories) may hit rate limits. Design workflows to paginate carefully and avoid unnecessary requests.\n- GraphQL API has separate rate limits based on query complexity.\n\n## Troubleshooting\n\n### Common Issues\n\n**Issue**: Tool not found or not available\n- **Solution**: Check if you're using `allowed:` to restrict tools. Consider using `toolsets:` instead to get all related tools.\n- **Verify**: Run `gh aw mcp inspect \u003Cworkflow-name>` to see which tools are actually available.\n\n**Issue**: Missing functionality after specifying toolset\n- **Cause**: Using a too-narrow toolset that doesn't include all needed tools\n- **Solution**: Either add additional toolsets (e.g., `toolsets: [default, actions]`) or use `[all]` for full access\n\n**Issue**: Workflow using `allowed:` list is verbose and hard to maintain\n- **Solution**: Migrate to `toolsets:` configuration using the migration guide above\n\n### Best Practices for Debugging\n\n1. **Start with `[default]` toolset**: Most workflows work well with default toolsets\n2. **Add specific toolsets as needed**: Incrementally add toolsets like `actions`, `discussions`, etc.\n3. **Use `gh aw mcp inspect`**: Verify which tools are actually available\n4. **Check tool-to-toolset mapping**: Reference the tables above to find the right toolset\n\n## References\n\n- [GitHub MCP Server Repository](https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgithub-mcp-server)\n- [Model Context Protocol Specification](https:\u002F\u002Fmodelcontextprotocol.io\u002F)\n- [GitHub Actions Documentation](https:\u002F\u002Fdocs.github.com\u002Factions)\n",{"name":5,"description":7},"main","8541229759617347888641eba917d3b0ad66a984",".github\u002Fskills\u002Fgithub-mcp-server",626,"https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw","https:\u002F\u002Fgh.io\u002Fgh-aw","https:\u002F\u002Fgithub.com\u002Fgithub","https:\u002F\u002Fgithub.com\u002Fabout","How people build software.","2026-11-15 06:45:15",{"source":8,"skillName":5,"commands":54,"prompt":64,"zipAvailable":65},[55,58,61],{"tool":56,"command":57},"npx","npx skills add github\u002Fgh-aw --skill github-mcp-server",{"tool":59,"command":60},"bunx","bunx skills add github\u002Fgh-aw --skill github-mcp-server",{"tool":62,"command":63},"pnpm","pnpm dlx skills add github\u002Fgh-aw --skill github-mcp-server","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fgithub-mcp-server\u002FSKILL.md",true,[],[68,76,84,108,125,150],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":75},"01M7DQYVZ9W9DDXKQ9452SNP8J","cracktro","Edit, preview, and verify the standalone interactive talk deck in docs\u002Fpublic\u002Fcracktro (slides, SVG diagrams, transitions, WebAudio sound).","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fcracktro\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":83},"01M7612HQ4378TK8QZ5HPAF4KR","create-connector","Create or extend a declaration-only third-party connector, with narrow reads, separate safe outputs, optional protected triggers, and offline conformance evidence.","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fcreate-connector\u002FSKILL.md",[],[],"2026-11-12 13:55:43",{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":94,"publishedAt":38},"01M6ADC942STTXHFV410J4DH0X","GitHub Agentic Workflows","GitHub Agentic Workflows (`gh-aw`) is a GitHub CLI extension for writing Agentic Workflows in markdown and compiling them to GitHub Actions.","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002FSKILL.md",[90,93],{"categoryNo":91,"categoryName":92,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000011","运维与部署",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[9,95,96,97,98,99,100,101,102,103,37,104,105,106,107],"github agentic workflows","agentic workflows","workflows","agentic","extension","markdown","github cli","cli","gh","compiling","writing","github actions","actions",{"skillNo":109,"name":110,"nameZh":6,"description":111,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":112,"categories":113,"keywords":114,"publishedAt":38},"01M6ADC6ZXSA46N9XD6VNAP1MS","windows-compatibility","Cross-platform path handling and command patterns","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fwindows-compatibility\u002FSKILL.md",[],[115,116,117,118,119,120,121,122,35,123,124],"windows","windows compatibility","compatibility","command","git","bugs","platform","high","cross-platform","path",{"skillNo":126,"name":127,"nameZh":6,"description":128,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":129,"categories":130,"keywords":131,"publishedAt":38},"01M6ADC44957SVQF96R5YY247P","versioning-policy","Semver versioning rules for Squad SDK and CLI — prevents prerelease version incidents","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fversioning-policy\u002FSKILL.md",[],[132,133,134,135,136,102,137,138,139,140,141,142,143,144,37,145,146,147,148,149],"versioning","policy","versioning policy","gate","implementation","workspace","pr","sdk","release","ci","npm","semver","squad","incident","incidents","Rules","version","resolution",{"skillNo":151,"name":152,"nameZh":6,"description":153,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":154,"categories":155,"keywords":160,"publishedAt":38},"01M6ADC1PHMEAEVR87F8PDR89X","tiered-memory","Three-tier agent memory model (hot\u002Fcold\u002Fwiki) for context reduction per spawn","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Ftiered-memory\u002FSKILL.md",[156,159],{"categoryNo":157,"categoryName":158,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[161,162,163,164,165,166,167,168,169,170,171,172,173,37,174,175],"tiered memory","memory","performance","design","agent memory","proposal","cold","model","wiki","spawn","memory-management","context","three","runtime","management"]