How to Configure GitHub MCP Tools for Issues, Pull Requests, and Repositories

Configure GitHub MCP tools by declaring toolsets in your workflow's tools.github configuration, choosing from predefined collections like issues, pull_requests, repos, actions, default, or all, rather than listing individual API methods.

Agentic workflows in the github/gh-aw repository access the GitHub API through the GitHub MCP (Model Context Protocol) tool. Modern configuration relies on toolsets—predefined collections of related API methods that replace legacy allowed: lists. This approach simplifies workflow files, automatically includes new endpoints as the API evolves, and integrates with the permission validator to ensure your GITHUB_TOKEN has the required scopes.

Understanding GitHub MCP Toolsets

Toolsets group related GitHub API functionality into logical collections. Instead of enumerating individual methods in an allowed list, you declare which high-level capabilities your workflow requires.

Toolset	What it enables	Typical use-case
repos	Repository CRUD, commits, releases, code search	Managing files, creating releases
issues	Create, list, comment, and react on issues	Issue-based automation
pull_requests	Create, list, approve, and merge PRs	PR reviewers, merge bots
actions	Workflow runs, artifacts, and logs	CI/CD introspection
default	Expands to context, repos, issues, pull_requests (users excluded)	General-purpose bots
all	Every GitHub toolset including projects and users	Full-privilege agents

Why Toolsets Replace Allowed Lists

The shift from explicit allowed arrays to toolsets provides three architectural advantages:

• Stability – New API endpoints are automatically added to the appropriate set, so your workflow stays functional without constant updates when the GitHub API expands.
• Permission-driven validation – The validator in pkg/workflow/permissions_validation.go (lines 94-104) expands default and checks that the workflow’s permissions: block grants the required scopes. The implementation of GitHubToolConfig.GetToolsets() handles the expansion logic.
• Simplified configuration – A single array entry replaces long allowed: lists, and the compiler warns if a toolset (e.g., projects) requires a Personal Access Token (PAT) instead of the default GITHUB_TOKEN.

Configuring GitHub MCP Tools in Workflow Files

Configuration occurs in the tools.github section of your workflow's YAML front matter. The struct definition in pkg/workflow/tools_types.go defines the available fields.

Basic Toolset Configuration

Specify the toolsets array to enable capabilities. The parser in pkg/workflow/tools_parser.go normalizes toolset and toolsets fields during parsing.

---
engine: copilot
tools:
  github:
    mode: remote
    toolsets: [issues, pull_requests]
    read-only: true
---

Authentication and Permission Modes

Control access levels through authentication settings:

• read-only – When set to true (default), write operations are blocked regardless of token permissions.
• github-token – Overrides the default GITHUB_TOKEN with a PAT or GitHub-App token.
• app – Configures GitHub App authentication for short-lived credentials (recommended for production).

The permission validator in pkg/workflow/permissions_validation.go (lines 122-131) checks required scopes against the embedded permissions map. If a required permission is missing, it prints a clear warning and remediation suggestion.

Enabling Lockdown for Public Repositories

For public repositories, enable the lockdown flag to filter user-generated content and prevent content-scraping by untrusted users.

---
engine: copilot
tools:
  github:
    mode: remote
    toolsets: [default]
    lockdown: true
---

The Lockdown field is defined in GitHubToolConfig in pkg/workflow/tools_types.go (line 70).

Toolset Expansion and Permission Validation

When the workflow compiler processes your configuration, it expands abstract toolsets into concrete API permissions.

The default toolset expands to context, repos, issues, and pull_requests through the GetToolsets() method implementation. This expansion occurs before permission validation.

The validator in pkg/workflow/permissions_validation.go performs two critical checks:

1. Toolset expansion (lines 94-104) – Resolves default to its constituent parts.
2. Permission mapping (lines 122-131) – Validates that your workflow's permissions: block includes the necessary scopes (e.g., issues: write for the issues toolset).

If validation fails, the compiler emits a warning suggesting either the reduction of toolsets or the addition of missing permissions.

Complete Configuration Examples

Minimal Read-Only Configuration

Enable only issues and pull_requests in remote mode with read-only access:

---
engine: copilot
tools:
  github:
    mode: remote
    toolsets: [issues, pull_requests]
    read-only: true
---

Full-Access Bot with Actions

Enable default plus actions with write permissions using a custom PAT:

---
engine: copilot
tools:
  github:
    mode: remote
    toolsets: [default, actions]
    read-only: false
    github-token: "${{ secrets.CUSTOM_PAT }}"
---

GitHub App Authentication

Use short-lived credentials via GitHub App for enhanced security:

---
engine: copilot
tools:
  github:
    mode: remote
    toolsets: [repos, issues]
    app:
      app-id: ${{ vars.APP_ID }}
      private-key: ${{ secrets.APP_PRIVATE_KEY }}
      owner: "my-org"
      repositories: ["my-repo"]
---

Public Repository with Lockdown

Prevent content-scraping in public repositories:

---
engine: copilot
tools:
  github:
    mode: remote
    toolsets: [default]
    lockdown: true
---

Custom MCP Server Integration

Combine GitHub toolsets with custom MCP servers:

---
engine: copilot
tools:
  github:
    toolsets: [repos]
  slack:
    command: "npx"
    args: ["-y", "@slack/mcp-server"]
    env:
      SLACK_BOT_TOKEN: "${{ secrets.SLACK_BOT_TOKEN }}"
    allowed: ["send_message", "get_channel_history"]
---

Summary

• GitHub MCP tools use toolsets—predefined collections like repos, issues, pull_requests, and actions—instead of individual API method lists.
• The default toolset expands to context, repos, issues, and pull_requests, providing a baseline for general-purpose automation.
• Configuration occurs in the tools.github section of workflow front matter, with fields for mode, read-only, github-token, app, and lockdown.
• The permission validator in pkg/workflow/permissions_validation.go automatically checks that your workflow's permissions: block matches the requirements of your selected toolsets.
• For public repositories, enable lockdown: true to restrict access to content from users with push access only.

Frequently Asked Questions

What is the difference between the default and all toolsets?

The default toolset expands to context, repos, issues, and pull_requests, covering the most common automation scenarios without including user management or projects. The all toolset grants access to every available GitHub toolset, including projects, users, and other specialized endpoints, which requires broader token permissions and should be used only when necessary.

How does the permission validator check my toolset configuration?

The validator in pkg/workflow/permissions_validation.go (lines 94-104 and 122-131) first expands toolsets like default into their constituent parts using GitHubToolConfig.GetToolsets(), then compares the required GitHub permissions against your workflow's permissions: block. If a mismatch is detected—such as requesting the issues toolset without issues: write permission—the compiler emits a warning suggesting either reducing toolsets or adding the missing permission.

Can I use a GitHub App instead of a Personal Access Token?

Yes, you can configure GitHub App authentication by adding an app: section to your tools.github configuration. Specify the app-id, private-key, and optionally the owner and repositories to scope the token. This method generates short-lived tokens automatically and is recommended for production environments according to the GitHubToolConfig.App struct definition in pkg/workflow/tools_types.go.

What is the purpose of the lockdown setting in public repositories?

The lockdown: true setting restricts the GitHub MCP tool to only access issues, pull requests, and comments from users who have push access to the repository. This prevents content-scraping by untrusted users in public repositories while still allowing the workflow to interact with content from maintainers and contributors. The flag is defined in GitHubToolConfig.Lockdown in pkg/workflow/tools_types.go (line 70).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}