Text of github.github.com › gh-aw › reference › github-tools as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

GitHub Tools (for reading from GitHub) | GitHub Agentic Workflows

Skip to main content GitHub Tools (for reading from GitHub) The GitHub Tools ( tools.github ) let the agentic step read information such as issues and pull requests from GitHub. In most workflows, no extra configuration is needed. The default toolset already provides access to the current repository and public repositories, subject to the network firewall. GitHub Toolsets Section titled “GitHub Toolsets” You can enable specific API groups to increase the available tools or narrow the default selection: tools : github : toolsets : [ repos , issues , pull_requests , actions ] Available : context , repos , issues , pull_requests , users , actions , code_security , discussions , labels , notifications , orgs , projects , gists , dependabot , secret_protection , security_advisories , stargazers Shorthand values : default — expands to context , repos , issues , pull_requests , users all — expands to all available toolsets except dependabot (see note below) Default : context , repos , issues , pull_requests , users Common toolsets include context (user and team info), repos (repository operations, code search, commits, releases), issues , pull_requests , actions (workflows, runs, artifacts), code_security , discussions , and labels .

Some toolsets require additional authentication . Code Search Rate Limits Section titled “Code Search Rate Limits” The GitHub MCP search_code tool uses a separate, much smaller budget than ordinary GitHub API reads. GitHub’s search rate limits allow 10 authenticated code-search requests per minute, compared with 30 per minute for other search endpoints. An available core quota does not imply that code search is available.

Agent start/end rate-limit snapshots log core , code_search , and search with their limit, remaining requests, and reset time. MCP HTTP 429 failures appear in the agent job summary with the server’s retry hint, when provided. These snapshots reflect the configured GitHub tools credential; they do not prove that concurrent runs share an identity or explain every secondary limit or MCP-server throttle. A retry hint is not a guarantee that waiting will make the next request succeed.

For inspecting code in another repository, the recommended alternative is checkout: with sparse-checkout , then local grep or rg searches. This checkout configuration is supported in v0.89.17: permissions: contents: read checkout: - repository: owner/target-repo ref: main path: target-repo sparse-checkout: | src docs github-token: ${{ secrets.TARGET_REPO_READ_TOKEN }} tools: bash: ["grep", "rg"] Use a token or GitHub App with read access to the target repository; the workflow’s GITHUB_TOKEN is scoped to its own repository.

The checkout credential is separate from tools.github authentication. Search the checked-out paths locally rather than fetching missing files during agent execution. For occasional API code searches, keep a small per-run max-calls limit ; it does not reserve quota or prevent throttling. Restricting Tools ( tools.github.allowed ) Section titled “Restricting Tools (tools.github.allowed)” Use tools.github.allowed to restrict which GitHub MCP tools the agent can call.

Each entry is either a string tool name or an object with a per-tool call limit: tools : github : allowed : - name : issue_read max-calls : 1 - list_labels - pull_request_read String entries ( list_labels ) — allow unlimited calls to that tool within the run. Object entries ( { name: <tool>, max-calls: <n> } ) — cap how many times the tool can be invoked. max-calls must be a positive integer; the MCP gateway enforces the cap at runtime.

The shorthand form "issue_read:1" is not interpreted as a call limit — it is treated as a literal (and therefore unknown) tool name. This complements toolset selection: toolsets decides which API groups are loaded, while allowed further narrows which individual tools the agent may invoke and how many times. GitHub Integrity Filtering ( tools.github.min-integrity ) Section titled “GitHub Integrity Filtering (tools.github.min-integrity)” Sets the minimum integrity level required for content the agent can access.

For public repositories, min-integrity: approved is applied automatically. See Integrity Filtering for levels, examples, user blocking, and approval labels. Guard Policy Frontmatter Examples Section titled “Guard Policy Frontmatter Examples” The GitHub tool supports guard-policy fields directly under tools.github : tools : github : allowed-repos : - " github/gh-aw " - " github/* " min-integrity : approved blocked-users : - " malicious-user " trusted-users : - " trusted-contributor " approval-labels : - " safe-for-agent " - " human-reviewed " GitHub Cross-Repository Reading Section titled “GitHub Cross-Repository Reading” By default, the GitHub Tools can read from the current repository and all public repositories, subject to the network firewall.

To read from other private repositories, configure additional authentication. You can further restrict repository access during execution with tools.github.allowed-repos . See Cross-Repository Operations for details and examples. GitHub Tools Access Modes Section titled “GitHub Tools Access Modes” The tools.github.mode field controls how the agent accesses GitHub. Three values are supported: Mode Transport Notes local (default) Docker-based GitHub MCP Server inside the Actions VM No extra authentication required remote Hosted GitHub MCP Server managed by GitHub Requires additional authentication gh-proxy Pre-authenticated gh CLI directly (no MCP server) Preferred for performance; required for integrity reactions remote mode — uses a hosted MCP server managed by GitHub.

Requires a GitHub token with appropriate permissions: tools : github : mode : remote github-token : ${{ secrets.CUSTOM_PAT }} # Required for remote mode gh-proxy mode — uses the pre-authenticated gh CLI directly instead of an MCP server. This offers lower latency because there is no MCP server startup overhead, and it is required for workflows that use integrity reactions . The legacy features: {cli-proxy: true} feature flag is equivalent and is still accepted for backward compatibility. tools : github : mode : gh-proxy CLI proxy startup diagnostics Section titled “CLI proxy startup diagnostics” The CLI proxy waits up to 30 seconds for readiness.

Startup diagnostics are captured in a private temporary directory outside artifact upload roots, with a 1 MiB input limit. Before publishing the last 20 lines, the startup script redacts built-in credential patterns and supplied secret values, including a custom GitHub token passed as GH_TOKEN . Unrelated workflow secrets are not automatically forwarded to the startup step. If capture exceeds the limit or sanitization fails, the step withholds the diagnostics and reports a fixed error instead of printing raw output.

Timeout diagnostics retain the readiness failure reason. Raw temporary diagnostics are removed on normal exit; a cleanup failure is reported and fails the step. Additional Authentication for GitHub Tools Section titled “Additional Authentication for GitHub Tools” In some circumstances you must use a GitHub PAT or GitHub app to give the GitHub tools used by your workflow additional capabilities. This authentication relates to reading information from GitHub.

Additional authentication to write to GitHub is handled separately through various Safe Outputs . This is required when your workflow needs read access to org or user information, other private repositories, projects, or GitHub tools remote mode . Using a Personal Access Token (PAT) Section titled “Using a Personal Access Token (PAT)” If additional authentication is required, one way is to create a fine-grained PAT with appropriate permissions, add it as a repository secret, and reference it in your workflow: Create a fine-grained PAT (this link pre-fills the description and common read permissions) with repository access to the repos you need

The rest of this page is on the live site.