Tools | GitHub Agentic Workflows
Skip to main content Tools Tools are defined in the frontmatter to specify which GitHub API calls, browser automation, and AI capabilities are available to your workflow: tools : edit : bash : true Some tools are available by default. All tools declared in imported components are merged into the final workflow. Built-in Tools Section titled “Built-in Tools” Edit Tool ( edit: ) Section titled “Edit Tool (edit:)” Allows file editing in the GitHub Actions workspace. tools : edit : GitHub Tools ( github: ) Section titled “GitHub Tools (github:)” Configure GitHub API operations including toolsets, remote/local modes, and authentication. tools : github : toolsets : [ repos , issues ] See GitHub Tools Reference for complete configuration options.
Linear Tools ( linear: ) Section titled “Linear Tools (linear:)” Linear is configured through an imported connector, not a built-in toolset. Import .github/workflows/connectors/linear.md , grant exact resources, and select tools.linear: [get-issue] or the reviewed hosted MCP registration. See Connectors . Jira connector Section titled “Jira connector” Import .github/workflows/connectors/jira.md and select tools.jira: [personal] or [service-account] with explicit grants.
The former auth / allowed built-in configuration is no longer supported. See the Jira connector reference . Bash Tool ( bash: ) Section titled “Bash Tool (bash:)” Enables shell command execution in the workspace. Defaults to safe commands ( echo , printf , ls , pwd , cat , head , tail , grep , wc , sort , uniq , date , yq ). tools : bash : # Default safe commands bash : [] # Disable all commands bash : [ " echo " , " ls " , " git status " ] # Specific commands only bash : [ " :* " ] # All commands (use with caution) Use wildcards like git:* for command families or :* for unrestricted access.
Web Tools Section titled “Web Tools” Enable web content fetching and search capabilities: tools : web-fetch : # Fetch web content web-search : # Search the web (engine-dependent) Engine behavior differs: Claude : Web search is off by default and enabled only when web-search: is declared. Codex : Enabled when either web-search: or web-fetch: is declared; the two cannot be disabled independently. With neither, Codex runs with -c web_search="disabled" .
Use network.hosted-web to restrict hosted retrieval. Copilot : Runs in offline BYOK mode, so native web tools are disabled. Compilation rejects web-search: and, in CLI mode, web-fetch: . With engine.copilot-sdk: true , web-fetch: works through a proxy-aware custom tool that follows network.allowed ; this does not enable native search. Gemini and Pi : No built-in web search. web-search: has no effect and gh aw compile prints a warning.
Copilot, Gemini, and Pi need a third-party MCP server for search (Copilot CLI mode also needs one for fetch). See Using Web Search . Playwright Tool ( playwright: ) Section titled “Playwright Tool (playwright:)” Configure Playwright for browser automation and testing: tools : playwright : version : " 1.56.1 " # Optional: specify version See the Playwright Reference for full configuration, network access, and browser support.
Cache Memory ( cache-memory: ) Section titled “Cache Memory (cache-memory:)” Persistent memory storage across workflow runs for trends and historical data. tools : cache-memory : See the Cache Memory Reference for full configuration and examples. Drive Memory ( drive-memory: ) — Private Preview Section titled “Drive Memory (drive-memory:) — Private Preview” An experimental, feature-gated GitHub Drives integration.
Do not configure it unless GitHub has enrolled the repository in the private preview. See the Drive Memory Reference . Repo Memory ( repo-memory: ) Section titled “Repo Memory (repo-memory:)” Repository memory that persists across executions. tools : repo-memory : See the Repo Memory Reference for full configuration and examples. QMD Documentation Search — Experimental Section titled “QMD Documentation Search — Experimental” Import a shared workflow to configure QMD Documentation Search , including its MCP server, indexing job, and cache-memory.
See the example shared workflow . Introspection on Agentic Workflows ( agentic-workflows: ) Section titled “Introspection on Agentic Workflows (agentic-workflows:)” Provides workflow introspection, log analysis, and debugging tools. Requires actions: read permission: permissions : actions : read tools : agentic-workflows : See GH-AW as an MCP Server for available operations. The built-in container runs as the runner’s UID and GID unless a container user is configured, so downloaded logs stay runner-owned and the post-agent secret-redaction step can read them.
Redaction failures still remove unsanitized sources and fail the step. The compile tool is read-only ( --no-emit ) by default. Remote imports and nested includes must already be cached; container validation does not pull missing Docker images. Workflow-writing tools ( add , update , fix ), emitted or dry-run compilation, and external scanners require opt-in at server startup: tools: agentic-workflows: allow-write-tools: true This sets --allow-write-tools while preserving actor validation.
It permits local workflow modifications and compiler scanner execution, not additional GitHub permissions or workflow dispatch. Enable it only for trusted clients and workflow sources. MCP CLI Mounting ( cli-proxy: ) Section titled “MCP CLI Mounting (cli-proxy:)” Set tools.cli-proxy: true to mount each user-facing MCP server as a standalone CLI tool on PATH , so the agent can invoke it from shell instead of through the MCP protocol: tools : cli-proxy : true With CLI mounting enabled, workflow-accessible servers such as safeoutputs and mcpscripts are wrapped as executables: Terminal window safeoutputs add_comment ' {"item_number":42,"body":"### Result\n\nIt\u0027s ready.\nQuoted text: \"hello\".\nLiteral path: C:\\temp\\file.txt"} ' mcpscripts mcpscripts-gh --args " issue list --limit 5 " For add_comment , use item_number , not issue_number (schema validation strips the latter).
Pass safe-output arguments as one single-quoted JSON object, encoding newlines as \n , double quotes as \" , backslashes as \\ , and apostrophes as \u0027 . Stdin also works: safeoutputs <tool_name> . reads a complete JSON object from stdin. CLI mounting only changes the agent-facing interface: mounted servers leave the MCP tool list, which can reduce token use from large tool schemas. Defaults to false . CLI mounting and gh-proxy mode both require shell access.
If tools.bash is disabled ( bash: false or bash: [] ), cli-proxy: true and tools.github.mode: gh-proxy are rejected at compile time, and strict mode requires cli-proxy: false to be set explicitly: tools : bash : false cli-proxy : false github : mode : local With cli-proxy: false and an MCP-backed GitHub mode ( local or remote ), servers such as safeoutputs stay on the MCP protocol and CLI instructions are omitted from the prompt.
Run gh aw fix to add the explicit setting to existing workflows. Tool Timeout Configuration Section titled “Tool Timeout Configuration” Tool Operation Timeout ( tools.timeout ) Section titled “Tool Operation Timeout (tools.timeout)” Sets the per-operation timeout in seconds when supported by the engine. Claude and Codex default to 60 seconds. For Codex, this configures native MCP tool calls, not shell-command duration.
Pi does not apply tools.timeout to shell commands. Use timeout-minutes for the overall execution limit. tools : timeout : 120 # seconds MCP Server Startup Timeout ( tools.startup-timeout ) Section titled “MCP Server Startup Timeout (tools.startup-timeout)” Sets the timeout in seconds for MCP server initialization. Default is 120 seconds. tools : startup-timeout : 60 # seconds Both fields accept integers or GitHub Actions expressions, so workflow_call workflows can parameterize them: tools : timeout : ${{ inputs.tool-timeout
The rest of this page is on the live site.