---
sidebar_position: 4
title: GitHub
---

# GitHub skill

Read repos, list and inspect PRs, search code and issues, read files, clone repositories, create issues.

- **ID:** `github`
- **MCP server:** `github` (tools exposed as `mcp__github__*`)
- **Underlying server:** `npx @modelcontextprotocol/server-github@latest`

## Tools provided

| Tool | What it does |
|---|---|
| `github_list_repos` | List accessible repos (private + public). Defaults to all installation repos when no `owner` given |
| `github_search_repos` | Substring search across accessible repo names and descriptions |
| `github_get_user` | Authenticated user (or GitHub App installation owner) |
| `github_list_orgs` | Organizations with accessible repos |
| `github_clone` | `git clone` a repo locally, defaulting to `~/zibby-repos/<repo>`; accepts `destination` |
| `github_get_file` | Read a file's content (or list a directory) at a `ref` |
| `github_list_commits` | Recent commits on a branch, optionally filtered by `path` |
| `github_get_commit` | Full commit details + per-file patches |
| `github_search_issues` | GitHub search-syntax across issues and PRs |
| `github_search_code` | Code search, optionally scoped to `repo` or `language` |
| `github_get_pr` | PR metadata (title, branch, stats) |
| `github_get_pr_diff` | Unified diff (capped at 15 KB) |
| `github_list_pr_files` | Files changed in a PR with per-file patches |
| `github_list_pr_comments` | Review + issue comments combined, sorted ascending |
| `github_create_issue` | Create a new issue |

## Setup

Two options:

**GitHub App (recommended).** In **Settings → Integrations**, click **Connect GitHub**, install the Zibby GitHub App on the orgs/repos you want, and authorize. Tokens auto-refresh; you don't manage them. See the [GitHub Integration page](../integrations/github.md) for the full app permissions list.

**Personal access token.** Set `GITHUB_TOKEN` in your agent's env (locally) or via **Cloud → Env vars** (cloud runs). Scope `repo` for private read+write, `public_repo` for public-only.

The skill reads `envKeys: ['GITHUB_TOKEN']` and the official `@modelcontextprotocol/server-github` consumes it directly.

## Use in an agent

```js
import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
import { SKILLS } from '@zibby/skills';

export class PrSummarizer extends WorkflowAgent {
  buildGraph() {
    const graph = new WorkflowGraph();
    graph.addNode('summarize_pr', {
      agent: 'claude',
      skills: [SKILLS.GITHUB],
      prompt: (state) => `Get PR #${state.prNumber} on ${state.owner}/${state.repo}.
      Read the diff with github_get_pr_diff and list reviewer comments with
      github_list_pr_comments. Produce a 4-bullet summary of what changed and any
      open review threads.`,
    });
    return graph;
  }
}
```

## Output example

`github_get_pr`:

```json
{
  "number": 142,
  "title": "fix(auth): refresh token on 401",
  "state": "open",
  "merged": false,
  "user": "alice",
  "branch": "fix-auth-refresh",
  "base": "main",
  "changedFiles": 3,
  "additions": 47,
  "deletions": 12,
  "url": "https://github.com/acme/app/pull/142",
  "labels": ["bug", "auth"]
}
```

## Implementation notes

`skill.resolve()` returns `{ command: 'npx', args: ['-y', '@modelcontextprotocol/server-github@latest'], env }` — the official upstream MCP server. The skill's `handleToolCall` implementation (with GitHub App-aware behavior for `/user` and `/user/orgs`) is used by the `assistant` agent strategy and by any caller that bypasses MCP.

For GitHub App installation tokens, `/user` and `/user/orgs` are server-to-server-forbidden; the in-process handlers transparently fall back to `/installation/repositories` and derive the owner/orgs from there.