GitHub Tools (for reading from GitHub)

The GitHub Tools (tools.github) allow the agentic step of your workflow to read information such as issues and pull requests from GitHub.

In most workflows, no configuration of the GitHub Tools is necessary since they are included by default with the default toolsets. By default, this provides access to the current repository and all public repositories (if permitted by the network firewall).

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, search, dependabot, experiments, secret_protection, security_advisories, stargazers

Default: context, repos, issues, pull_requests, users

Some key toolsets are:

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 (discussions and comments)
labels (labels management)

Some toolsets requuire additional authentication.

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.

GitHub Repository Access Restrictions (`tools.github.allowed-repos`)

You can configure the GitHub Tools to be restricted in which repositories can be accessed via the GitHub tools during AI engine execution.

The setting tools.github.allowed-repos specifies which repositories the agent can access through GitHub tools:

"all" — All repositories accessible by the configured token
"public" — Public repositories only
Array of patterns — Specific repositories and wildcards:
- "owner/repo" — Exact repository match
- "owner/*" — All repositories under an owner
- "owner/prefix*" — Repositories with a name prefix under an owner

This defaults to "all" when omitted. Patterns must be lowercase. Wildcards are only permitted at the end of the repository name component.

For example:

tools:
  github:
    mode: remote
    toolsets: [default]
    allowed-repos:
      - "myorg/*"
      - "partner/shared-repo"
      - "myorg/api-*"
    min-integrity: approved

GitHub Cross-Repository Reading

By default, the GitHub Tools can read from the current repository and all public repositories (if permitted by the network firewall). To read from other private repositories, you must configure additional authentication. See Cross-Repository Operations for details and examples.

GitHub Tools Remote Mode

By default the GitHub Tools run in “local mode”, where the GitHub MCP Server runs within the GitHub Actions VM hosting your agentic workflow. You can switch to “remote mode”, which uses a hosted MCP server managed by GitHub. Remote mode requires additional authentication and enables additional filtering and capabilities.

tools:
  github:
    mode: remote  # Default: "local" (Docker)
    github-token: ${{ secrets.CUSTOM_PAT }}  # Required for remote mode

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 requires any of the following:

Read access to GitHub org or user information
Read access to other private repos
Read access to projects
GitHub tools Remote Mode

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:
  - Select specific repos or “All repositories”
- Repository permissions (based on your GitHub tools usage):
  - Contents: Read (minimum for toolset: repos)
  - Issues: Read (for toolset: issues)
  - Pull requests: Read (for toolset: pull_requests)
  - Projects: Read (for toolset: projects)
  - Security Events: Read (for toolset: dependabot, code_security, secret_protection, security_advisories)
  - Remote mode: no additional permissions required
  - Adjust based on the toolsets you configure in your workflow
- Organization permissions (if accessing org-level info):
  - Members: Read (for org member info in context)
  - Teams: Read (for team info in context)
  - Adjust based on the toolsets you configure in your workflow
Add it to your repository secrets, either by CLI or GitHub UI:
Terminal window
```
gh aw secrets set MY_PAT_FOR_GITHUB_TOOLS --value "<your-pat-token>"
```

Configure in your workflow frontmatter:

tools:
  github:
    github-token: ${{ secrets.MY_PAT_FOR_GITHUB_TOOLS }}

Using a GitHub App

Alternatively, you can use a GitHub App for enhanced security. See Using a GitHub App for Authentication for complete setup instructions.

Using a magic secret

Alternatively, you can set the magic secret GH_AW_GITHUB_MCP_SERVER_TOKEN to a suitable PAT (see the above guide for creating one). This secret name is known to GitHub Agentic Workflows and does not need to be explicitly referenced in your workflow.

gh aw secrets set GH_AW_GITHUB_MCP_SERVER_TOKEN --value "<your-pat-token>"

Using the `dependabot` toolset

The dependabot toolset can only be used if authenticating with a PAT or GitHub App and also requires the vulnerability-alerts GitHub App permission. If you are using a GitHub App (rather than a PAT), add vulnerability-alerts: read to your workflow’s permissions: field and ensure the GitHub App is configured with this permission. See GitHub App-Only Permissions.

Tools Reference - All tool configurations
Authentication Reference - Token setup and permissions
Integrity Filtering - Public repository content filtering
MCPs Guide - Model Context Protocol setup