> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polycore.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Read repositories, issues, pull requests, and Actions runs through GitHub's own MCP server, governed by Polycore.

GitHub is a **direct integration**: Polycore hosts the connection to GitHub's
own remote MCP server, so there is no runner to deploy and nothing to build.
An owner or admin connects it once per project, and everyone in the connection's
audience can ask about repositories, issues, pull requests, and Actions runs
from Slack, the dashboard, an MCP client, or a page.

GitHub owns the tools. Polycore owns everything that makes them governed: who
may use the connection, which tools are enabled, how hazardous each one is,
whether a call runs or waits for a human, and the audit row that names both the
caller and the GitHub account the call acted as.

## Architecture

```mermaid theme={"system"}
flowchart LR
  Caller["Agent, Slack, dashboard, page"]
  CP["Polycore control plane"]
  Executor["Private integration executor"]
  GH["api.githubcopilot.com/mcp"]

  Caller --> CP --> Executor --> GH
```

The control plane never holds the token. It holds the connection, the pinned
tool list, and the audit trail. The token is sealed with envelope encryption in
an isolated executor that is unreachable from the public internet, and the
executor refuses any request or redirect that leaves `api.githubcopilot.com`.

## What it can do

Polycore connects to the `context`, `repos`, `issues`, `pull_requests`, and
`actions` toolsets, and classifies every tool GitHub advertises:

* **Reads** run when they are called: listing commits, reading files, searching
  issues and pull requests, reading Actions runs and job logs.
* **Writes** wait for one human approval: filing and editing issues, commenting,
  opening and merging pull requests, committing files, running workflows.
* **Anything else** GitHub adds that Polycore has not classified is treated as
  unknown. It is gated like a write, and it arrives **disabled** so an admin
  reviews it before anyone can call it.

<Warning>
  This is shared authority, not personal GitHub access. Everyone in the
  connection's audience acts through the one token, reaching repositories their
  own GitHub account may not be able to open, and writes are attributed to the
  account that authorized the connection. The token's repository scope is the
  resource boundary, so grant it narrowly.
</Warning>

## Connect it

1. In GitHub, create a
   [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new).
   Select only the repositories this connection should reach, and grant read
   access to Metadata, Contents, Issues, Pull requests, and Actions.
2. In Polycore, open **Project settings → Integrations**, pick **GitHub**, and
   choose **Connect**.
3. Give the connection a name and a namespace. The namespace prefixes every
   capability, so `code` makes `code/list_pull_requests`.
4. Paste the token and choose who may use it: everyone in the organization, or
   owners and admins only.

The token crosses to the executor once, in memory, and is never returned,
logged, or shown again. Polycore then asks GitHub who the token acts as and
what tools it advertises, and pins both to the connection.

## Using it

Ask in Slack, or from any front door:

```text theme={"system"}
What merged in acme/web this week?
```

The audit row records the caller, the connection, the tool, and the GitHub
login the call acted as, so "who read this, as whom" is answerable without
reading logs.

Capabilities appear in the catalog under the connection's namespace:

```ts theme={"system"}
await polycore.run("code/list_pull_requests", {
  owner: "acme",
  repo: "web",
  state: "closed",
});
```

Agent and MCP tool names are `direct__<namespace>__<tool>`.

## When GitHub changes its tools

GitHub adds and changes tools on its own schedule. **Refresh tools** on the
connection re-lists them and shows the difference: schemas and descriptions are
updated in place, tools GitHub no longer offers are marked, and anything new
arrives **disabled** until an admin reviews it. A vendor cannot widen what your
project can call without someone looking at it first.

## Limits

* **Token, not OAuth.** A fine-grained personal access token today; connecting
  with a GitHub App is next.
* **One connection per GitHub account.** Add a second connection with its own
  namespace for a second account or a different repository scope.

## Removing it

**Remove connection** stops calls at once, drops the tools from the catalog, and
deletes the encrypted credential. Polycore cannot revoke the token at GitHub, so
delete or rotate it there too. The audit history stays.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.