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

> Configure GitHub MCP tools for issues, PRs, and repos easily. Learn how to declare toolsets in your workflow for efficient GitHub automation and management.

- Repository: [GitHub/gh-aw](https://github.com/github/gh-aw)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/pkg/workflow/tools_parser.go) normalizes `toolset` and `toolsets` fields during parsing.

```yaml
---
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`](https://github.com/github/gh-aw/blob/main/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.

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

```

The `Lockdown` field is defined in `GitHubToolConfig` in [`pkg/workflow/tools_types.go`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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:

```yaml
---
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:

```yaml
---
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:

```yaml
---
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:

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

```

### Custom MCP Server Integration

Combine GitHub toolsets with custom MCP servers:

```yaml
---
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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/pkg/workflow/tools_types.go) (line 70).