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

# GitHub

> Connect Aperium to GitHub repositories, pull requests, and issues, with approval-gated writes that act as the connected user.

The GitHub integration lets each user link their own GitHub account so agents can search repositories, pull requests, and issues, and, with approval, comment, review, and manage issues on their behalf. Aperium always acts as the connected user ("act as me") — every read and write runs under that user's GitHub identity and permissions. GitHub Enterprise Server is supported through the bring-your-own-app method below.

<Note>
  This is a **per-user** integration. There is no tenant-wide bot and no `aperium[bot]` identity — Aperium only ever acts as the individual who connected.
</Note>

## Choose a connection method

GitHub offers two ways to connect. Which one is the default depends on how your deployment is provisioned.

<AccordionGroup>
  <Accordion title="Device flow (no admin setup)">
    A credential-free connect against Aperium's built-in GitHub App. The user starts the connect from their Integrations page, approves at `github.com/login/device`, and is done — no admin registration required. This path is **github.com only** and is the default when the deployment ships the app's public client ID.
  </Accordion>

  <Accordion title="GitHub App (bring your own — required for Enterprise)">
    A tenant admin registers their own GitHub OAuth App and enters its **client ID** and **client secret** in Aperium. Users then connect through the standard GitHub web consent flow. This is also the path for **GitHub Enterprise Server** — the API endpoints are read from the tenant credential.
  </Accordion>
</AccordionGroup>

## What you'll need

* For device flow: nothing — users connect themselves.
* For the GitHub App method: rights to [register a GitHub OAuth App](https://github.com/settings/developers) for your organization (or Enterprise instance), and its client ID and client secret.

## Setup (GitHub App method)

<Steps>
  <Step title="Register a GitHub OAuth App">
    In GitHub's developer settings, create an OAuth App for your organization. For GitHub Enterprise Server, register it on your Enterprise instance so its endpoints resolve to your host.
  </Step>

  <Step title="Add the redirect URL">
    Aperium's setup form displays the exact redirect (callback) URL to register in GitHub. Copy it from the form into your OAuth App's authorization callback URL. Do not hand-craft this value — use the one Aperium shows.
  </Step>

  <Step title="Paste the credentials into Aperium">
    Open either the **admin onboarding flow** (first sign-in) or the **Admin Console's MCP Servers tab**, open the **Connect Aperium to GitHub** form, and enter the **OAuth Client ID** and **OAuth Client Secret**. Once saved, every user can link their GitHub account from the Integrations page.
  </Step>

  <Step title="(Optional) Set defaults and aliases">
    The setup guide accepts an optional **default repository**, plus **repository aliases** and **people aliases** (both JSON), so agents can resolve friendly names to `owner/repo` and to GitHub logins.
  </Step>
</Steps>

## What agents can do

**Read** — search repositories, pull requests, issues, and pending commits (compare); fetch a pull request in full; list release notes; and resolve the connected identity (whoami).

**Write (approval-gated)** — comment on a pull request or issue, submit a pull-request review, and create, update, close, or assign issues. Every write pauses for human approval before it runs, posts as the connected user, and free-text bodies carry a `via aperium (requested by @<login>)` footer. Issue writes are limited to create / update / close / assign; label and milestone management are out of scope.

## Notes

* **Permissions are the gate.** GitHub App user tokens carry no OAuth scopes; access is governed by the app's fine-grained permissions. A permission shortfall surfaces at tool-call time, not at connect time.
* **No repo guessing.** Write and compare tools require an explicit repository — they never fall back to a hidden default.
* **Multiple accounts.** A user can link more than one GitHub account; each is tracked as a separate connection.