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

Edit Tool (edit:)

Allows file editing in the GitHub Actions workspace.

tools:
  edit:

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:)

Connect to Linear’s official hosted MCP server with the LINEAR_API_KEY GitHub Actions secret:

tools:
  linear: {}

Set token to use a different secret, toolsets to enable groups such as issues and projects, allowed to further restrict tool names, and required: false to make connectivity best-effort:

tools:
  linear:
    token: ${{ secrets.CUSTOM_LINEAR_TOKEN }}
    toolsets: [issues, projects]
    allowed: ["*"]
    required: true

Supported toolsets are all, attachments, comments, customers, cycles, diffs, documentation, documents, initiatives, issues, milestones, projects, status_updates, teams, and users. The compiler expands toolsets into the gateway’s allowed-tool list, and any allowed names or wildcards must match a tool in the selected toolsets.

Linear always uses Linear’s server-enforced read-only endpoint. The credential is passed to the gateway as an environment variable and sent as an Authorization: Bearer header, not embedded in MCP configuration. Like other remote MCP servers, Linear also works with tools.cli-proxy: true.

Jira Tools (jira:)

Connect to Atlassian’s official remote Rovo MCP endpoint from non-interactive GitHub Actions workloads. Browser OAuth, device login, and user-consent flows are not supported.

Use an Atlassian service account API key:

tools:
  jira:
    auth:
      type: service-account
      token: ${{ secrets.ATLASSIAN_SERVICE_ACCOUNT_API_KEY }}
    allowed:
      - getJiraIssue
      - searchJiraIssuesUsingJql

Or use an Atlassian account email and API token:

tools:
  jira:
    auth:
      type: api-token
      email: ${{ secrets.ATLASSIAN_EMAIL }}
      token: ${{ secrets.ATLASSIAN_API_TOKEN }}
    allowed:
      - getJiraIssue
      - searchJiraIssuesUsingJql

The allowed list is required and accepts only these read-only Jira tools: getIssueLinkTypes, getJiraIssue, getJiraIssueRemoteIssueLinks, getJiraIssueTypeMetaWithFields, getJiraProjectIssueTypesMetadata, getTransitionsForJiraIssue, getVisibleJiraProjects, lookupJiraAccountId, and searchJiraIssuesUsingJql.

allowed: ["*"] is shorthand for enabling that fixed list at compile time; it never grants access to the full, unrestricted MCP tool set. Omitting allowed or naming a write-capable tool is rejected.

The endpoint defaults to https://mcp.atlassian.com/v1/mcp. Set url only when your organization uses another HTTPS Atlassian MCP endpoint. Credentials must be direct GitHub Actions secret expressions; service account keys use the HTTP bearer scheme while API tokens use HTTP Basic authentication generated at runtime.

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

Enable web content fetching and search capabilities:

tools:
  web-fetch:   # Fetch web content
  web-search:  # Search the web (engine-dependent)

Note: Some engines require third-party Model Context Protocol (MCP) servers for web search. See Using Web Search.

Web search is disabled by default for Codex, Claude, and Copilot. Claude and Copilot enable it only when web-search: is declared. Codex enables a shared native search/browsing tool when either web-search: or web-fetch: is declared; the two capabilities cannot be disabled independently. With neither tool, Codex runs with -c web_search="disabled". Use network.hosted-web to restrict Codex’s hosted retrieval.

The Gemini and Pi engines have no built-in web search. Declaring web-search: with either engine has no effect, and gh aw compile prints a warning. To search the web with these engines, configure a third-party MCP server as described in Using Web Search.

Playwright Tool (playwright:)

Configure Playwright for browser automation and testing:

tools:
  playwright:
    version: "1.56.1"  # Optional: specify version

See Playwright Reference for complete configuration options, network access, browser support, and example workflows.

Cache Memory (cache-memory:)

Persistent memory storage across workflow runs for trends and historical data.

tools:
  cache-memory:

See Cache Memory Reference for complete configuration options and usage examples.

Drive Memory (drive-memory:) — Private Preview

Drive memory is an experimental, feature-gated GitHub Drives integration. Do not configure it unless GitHub has explicitly enrolled the repository in the private preview.

The Drive Memory Reference records the preview behavior for enrolled repositories; it is not a recommendation for general use.

Repo Memory (repo-memory:)

Repository-specific memory storage for maintaining context across executions.

tools:
  repo-memory:

See Repo Memory Reference for complete configuration options and usage examples.

QMD Documentation Search (qmd:) — Experimental

Build a local vector search index over documentation files and expose it as an MCP search tool. The index is built in a dedicated indexing job (no contents: read needed in the agent job):

tools:
  qmd:
    checkouts:
      - pattern: "docs/**/*.md"

See QMD Documentation Search for complete configuration options, checkout support, GitHub search integration, and cache key usage.

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.

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:

safeoutputs add_comment --item_number 42 --body "Analysis complete"
mcpscripts mcpscripts-gh --args "issue list --limit 5"

For add_comment, use --item_number rather than --issue_number; schema validation strips the latter. CLI mounting changes only the agent-facing interface: the MCP gateway still starts normally, but mounted servers are removed from the MCP tool list and accessed via shell. This can reduce token use from large tool schemas and simplify prompts when shell-style invocation is preferred.

Defaults to false.

CLI mounting requires shell access because the wrappers are ordinary executables invoked from bash. GitHub gh-proxy mode is also shell-backed because GitHub reads are performed with the gh CLI. When 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 stated explicitly:

tools:
  bash: false
  cli-proxy: false
  github:
    mode: local

With cli-proxy: false and an MCP-backed GitHub mode (local or remote), MCP servers (including safeoutputs) remain available through the MCP protocol, and the CLI-only instructions are omitted from the generated prompt. Run gh aw fix to add the explicit setting to existing workflows.

Tool Timeout Configuration

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; use timeout-minutes for the overall execution limit.

tools:
  timeout: 120   # seconds

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 either an integer or a GitHub Actions expression string, enabling workflow_call reusable workflows to parameterize these values:

tools:
  timeout: ${{ inputs.tool-timeout }}
  startup-timeout: ${{ inputs.startup-timeout }}

Note

Expression values are passed through environment variables and resolved before execution. Codex’s configuration renderer converts the resolved values into numeric TOML settings; expressions do not fall back to defaults. An explicit per-server timeout in engine.config takes precedence over tools.timeout or tools.startup-timeout.

Custom MCP Servers (mcp-servers:)

Integrate custom Model Context Protocol servers for third-party services:

mcp-servers:
  slack:
    command: "npx"
    args: ["-y", "@slack/mcp-server"]
    env:
      SLACK_BOT_TOKEN: "${{ secrets.SLACK_BOT_TOKEN }}"
    allowed: ["send_message", "get_channel_history"]

Options: command + args (process-based), container (Docker image), url + headers (HTTP endpoint), registry (MCP registry URI), env (environment variables), allowed (tool restrictions), required (startup criticality). See MCPs Guide for setup.

Required Field

MCP servers must pass a startup connectivity check before the agent starts. By default every server is startup-critical: if it cannot be reached, the workflow fails. Set required: false to mark a server as best-effort, so an unreachable server logs a warning and the workflow continues without it:

mcp-servers:
  datadog:
    type: http
    url: "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp"
    required: false

Use this for optional integrations whose transient outages (for example an HTTP 503 from a hosted endpoint) should not take down the other configured servers. At least one server must still connect successfully for startup to proceed.

Registry Field

The registry field specifies the source URI of an MCP server in a registry. It is informational — useful for documenting server origin and enabling registry-aware tooling — and does not affect execution. gh-aw does not enforce registry usage. Works with both stdio and HTTP servers:

mcp-servers:
  filesystem:
    registry: "https://api.mcp.github.com/v0/servers/modelcontextprotocol/filesystem"
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem"]

Learn More

See GitHub Tools for GitHub API operations, toolsets, and modes; Playwright for browser automation; Cache Memory and Repo Memory for persistent context; MCP Scripts for custom inline tools; and MCPs for end-to-end Model Context Protocol setup.