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

# GitHub

> Open GitHub issues for prioritized actions automatically — as a real GitHub App.

When the agent proposes a `github_issue` action (in write mode), it opens a new issue in your repository. Issues are opened by the **App Co-founder GitHub App** so they show up as `app-co-founder[bot] opened this issue`.

## Two setup options

| Option                    | Use when                 | Setup time |
| ------------------------- | ------------------------ | ---------- |
| **GitHub App install** ⭐  | Production / SaaS use    | 30 sec     |
| **Personal Access Token** | Quick one-off, scripting | 2 min      |

The App is the recommended path because:

* **Per-repo install** — you grant access only to the repos you want, not your whole account.
* **Bot identity** — issues are opened by `app-co-founder[bot]`, not your user.
* **Higher rate limits** — 5000 req/h *per installation*, not shared with your user account.
* **Short-lived tokens** — installation tokens are minted on demand and expire in 1 hour, so a leaked token has limited blast radius.
* **Org-friendly** — an org admin can install once and many people benefit.

***

## Option A — Install the App (one click)

```
GET /v1/cofounder/oauth/github/start?return_to=<your-page>
   →  { authorizeUrl, state }
```

`authorizeUrl` redirects to `https://github.com/apps/app-co-founder/installations/new?state=<s>`. The user picks **which repositories** to grant access to. After install, GitHub redirects back to:

```
https://api.appeeky.com/v1/cofounder/oauth/github/callback
   ?installation_id=12345&setup_action=install&state=<s>&code=<optional>
```

We persist `installation_id` and (optionally) the GitHub `login` as `oauth_account_label`. No long-lived token is stored.

Then tell the agent which repo to file issues in:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PUT https://api.appeeky.com/v1/cofounder/integrations/github \
  -H "X-API-Key: $APPEEKY_KEY" \
  -d '{ "integrationConfig": { "owner": "Eronred", "repo": "appeeky-api-mcp" } }'
```

The repo must be one you granted the App access to. The integration test calls
`GET /repos/<owner>/<repo>` with a freshly minted installation token to confirm.

Enable in preferences:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
PUT /v1/cofounder/preferences { "agentMode": "write", "enabledIntegrations": ["github"] }
```

### Adding more repos later

Open [https://github.com/settings/installations](https://github.com/settings/installations) → App Co-founder → **Configure** → repositories. The agent picks the change up immediately (no re-OAuth needed).

### Switching repos

Same `PUT /integrations/github` call — pass a new `{ owner, repo }`. Multiple repos in one integration aren't supported yet; one repo per owner email.

***

## Option B — Personal Access Token (manual)

Useful for scripts or accounts where installing the App isn't an option.

1. Create a PAT: [https://github.com/settings/tokens?type=beta](https://github.com/settings/tokens?type=beta) — needs `repo` (or `public_repo` for OSS) scope.
2. Note the `owner` and `repo` (e.g., `Eronred/appeeky-api-mcp`).

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PUT https://api.appeeky.com/v1/cofounder/integrations/github \
  -H "X-API-Key: $APPEEKY_KEY" \
  -d '{
    "credentials": { "token": "github_pat_..." },
    "integrationConfig": { "owner": "Eronred", "repo": "appeeky-api-mcp" }
  }'
```

The integration is tested before saving — `GET /user` confirms the token, then `GET /repos/<owner>/<repo>` confirms repo access.

PAT-backed issues are opened by **your user** (not the bot).

***

## What gets created

```jsonc theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "github_issue",
  "title": "Fix v3.2.1 crash on launch",
  "body": "5 one-star reviews in 24h mention crash on launch on iOS 17.4...",
  "labels": ["bug", "ios", "high-priority"]
}
```

GitHub receives a regular issue with the title, body (markdown), and labels (created on the fly if missing — your installation must allow it).

## Auto-approve

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
PUT /v1/cofounder/preferences { "autoApproveTypes": ["github_issue"] }
```

GitHub issues are reversible (close = effectively undone), so auto-approve is generally safe.

## Disable

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
PUT /v1/cofounder/preferences { "enabledIntegrations": [] }
```

Or remove `"github"` from the array. Credentials remain stored — re-enable any time without re-install.

## Uninstall

Open [https://github.com/settings/installations](https://github.com/settings/installations) → **App Co-founder** → Uninstall. The next agent run will fail to mint an installation token; remove the integration row with `DELETE /v1/cofounder/integrations/github` to clean up.

## Server configuration

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
GITHUB_APP_ID=3584946
GITHUB_APP_SLUG=app-co-founder
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
GITHUB_CLIENT_ID=Iv23li...
GITHUB_CLIENT_SECRET=...
```

The private key signs short-lived JWTs that are exchanged for 1-hour installation tokens. The Client ID/Secret pair is only needed when "Request user authorization (OAuth) during installation" is enabled — it's used solely to fetch the installer's `login` for the friendly account label.