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.

Bash Tool (bash:)

Enables shell command execution in the workspace. Defaults to safe commands (echo, ls, pwd, cat, head, tail, grep, wc, sort, uniq, date).

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.

For the Codex engine, web-search: is disabled by default. Web search is only enabled when web-search: is explicitly declared in the tools: block. Without this declaration, Codex runs with -c web_search="disabled" and cannot access the web.

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.

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.

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.

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). See MCPs Guide for setup.

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. 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"]

Related Documentation

• GitHub Tools - GitHub API operations, toolsets, and modes
• Playwright - Browser automation and testing configuration
• Cache Memory - Persistent memory across workflow runs
• Repo Memory - Repository-specific memory storage
• MCP Scripts - Define custom inline tools with JavaScript or shell scripts
• Frontmatter - All frontmatter configuration options
• Network Permissions - Network access control for AI engines
• MCPs - Complete Model Context Protocol setup and usage