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.

Edit Tool (edit:)

Allows file editing in the GitHub Actions workspace.

tools:
  edit:

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 MCP servers for web search. See Using Web Search.

GitHub Tools (github:)

Configure GitHub API operations.

tools:
  github:                                      # Default read-only access
  github:
    toolsets: [repos, issues, pull_requests]   # Recommended: toolset groups
    mode: remote                               # "local" (Docker) or "remote" (hosted)
    read-only: true                            # Read-only operations
    github-token: "${{ secrets.CUSTOM_PAT }}"  # Custom token

GitHub Toolsets

Use Toolsets Instead of Allowed

Toolsets provide a stable API across MCP server versions and automatically include new related tools. See Migration from Allowed to Toolsets for guidance.

Enable specific API groups to improve tool selection and reduce context size:

tools:
  github:
    toolsets: [repos, issues, pull_requests, actions]

Available: context, repos, issues, pull_requests, users, actions, code_security, discussions, labels, notifications, orgs, projects, gists, search, dependabot, experiments, secret_protection, security_advisories, stargazers

Default: context, repos, issues, pull_requests, users

GitHub Actions Compatibility

toolsets: [default] expands to [context, repos, issues, pull_requests] (excluding users) since GITHUB_TOKEN lacks user permissions. Use a PAT for the full default set.

Common combinations: [default] (read-only), [default, discussions] (issue/PR), [default, actions] (CI/CD), [default, code_security] (security), [all] (full access)

Toolset Contents

Key toolsets: context (user/team info), repos (repository operations, code search, commits, releases), issues (issue management, comments, reactions), pull_requests (PR operations), actions (workflows, runs, artifacts), code_security (scanning alerts), discussions, labels.

Tip

The allowed: field is not recommended for GitHub tools since tool names may change between versions. Use toolsets: for stability. For custom MCP servers, allowed: remains the standard approach.

Modes and Restrictions

Remote Mode: Use hosted MCP server for faster startup (no Docker). Requires GH_AW_GITHUB_TOKEN:

tools:
  github:
    mode: remote  # Default: "local" (Docker)

Setup: gh aw secrets set GH_AW_GITHUB_TOKEN --value "<your-pat>"

Read-Only: Default behavior; restricts to read operations unless write operations configured.

Lockdown: Filter public repository content to items from users with push access. Private repos unaffected:

tools:
  github:
    lockdown: true

Playwright Tool (playwright:)

Enables containerized browser automation with domain-based access control:

tools:
  playwright:
    allowed_domains: ["defaults", "github", "*.custom.com"]
    version: "1.56.1"  # Optional: defaults to 1.56.1, use "latest" for newest

Domain Access: Uses network: ecosystem bundles (defaults, github, node, python, etc.). Defaults to ["localhost", "127.0.0.1"]. Domains auto-include subdomains.

Built-in MCP Tools

Agentic Workflows (agentic-workflows:)

Provides workflow introspection, log analysis, and debugging tools. Requires actions: read permission:

permissions:
  actions: read
tools:
  agentic-workflows:

See MCP Server for available operations.

Cache Memory (cache-memory:)

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

tools:
  cache-memory:

Repo Memory (repo-memory:)

Repository-specific memory storage for maintaining context across executions.

tools:
  repo-memory:

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), env (environment variables), allowed (tool restrictions). See MCPs Guide for setup.

Related Documentation

• Safe Inputs - 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
• CLI Commands - CLI commands for workflow management
• Workflow Structure - Directory layout and organization
• Imports - Modularizing workflows with includes