github-api

# github-api skill

## When to use

Use this skill when the user needs to:
- Fetch open pull requests for a repository via the GitHub REST API
- Match PR records to local Git branch names
- Handle GitHub API rate limiting and pagination
- Configure Octokit for GitHub Enterprise or github.com
- Store and manage GitHub personal access tokens securely

## Prerequisites

- Node.js 20+
- `@octokit/rest` npm package
- GitHub personal access token with scope `read:repo`

## Installation

```
pnpm add @octokit/rest
```

## Quick Start

```typescript
import { Octokit } from '@octokit/rest';

const octokit = new Octokit({ auth: process.env.GBDASH_GITHUB_TOKEN });

const { data } = await octokit.rest.pulls.list({
  owner: 'my-org',
  repo: 'my-repo',
  state: 'open',
  per_page: 100,
});
```

## Usage Patterns

### Listing open pull requests

The `pulls.list` endpoint returns up to 100 PRs per page. For repositories with more than 100 open PRs, paginate using `octokit.paginate`:

```typescript
const prs = await octokit.paginate(octokit.rest.pulls.list, {
  owner,
  repo,
  state: 'open',
  per_page: 100,
});
```

### Matching PRs to branch names

The `head.ref` field on each PR contains the source branch name. Match it against `branches.name` in the local database:

```typescript
for (const pr of prs) {
  const branch = branchMap.get(pr.head.ref);
  if (branch) {
    branch.pr_id = pr.id.toString();
  }
}
```

### Handling rate limits

The GitHub REST API allows 5000 requests per hour for authenticated requests. Check the `x-ratelimit-remaining` response header:

```typescript
const { data, headers } = await octokit.rest.pulls.list({ owner, repo, state: 'open' });
const remaining = parseInt(headers['x-ratelimit-remaining'] ?? '5000', 10);
if (remaining < 100) {
  // log a warning
}
```

Octokit automatically retries 429 responses with the `retry` plugin.

### GitHub Enterprise

Point Octokit at an Enterprise base URL:

```typescript
const octokit = new Octokit({
  auth: token,
  baseUrl: 'https://github.mycompany.com/api/v3',
});
```

### Token security

Never log the token or include it in API responses. Store it in:
- Config file: `~/.git-branch-dashboard/config.json` with file permissions `0600`
- Or environment variable: `GBDASH_GITHUB_TOKEN`

The config loader sets permissions on write:

```typescript
import { chmod, writeFile } from 'node:fs/promises';
await writeFile(configPath, JSON.stringify(config, null, 2), 'utf8');
await chmod(configPath, 0o600);
```

## API Reference

### `listOpenPRs(owner: string, repo: string): Promise<PRRecord[]>`

Fetches all open pull requests for the given repository and returns them as `PRRecord` objects.

Fields returned per PR:
- `pr_number` - GitHub PR number
- `pr_title` - PR title
- `pr_url` - URL to the PR on github.com
- `pr_state` - always `"open"` for this call
- `pr_author` - login of the PR author
- `branch_name` - `head.ref` value (source branch name)
- `pr_created_at` - ISO 8601 creation timestamp

Fields NOT returned (security):
- The GitHub token used to fetch the data
- Any internal GitHub IDs beyond `pr_number`

## GitHub Token Scopes

| Scope | Purpose |
|---|---|
| `read:repo` (public repos) | List PRs on public repositories |
| `repo` (private repos) | List PRs on private repositories |
| `read:org` | Required if the repo belongs to a GitHub org with SSO |

For most use cases, create a fine-grained personal access token with `Pull requests: Read-only` permission scoped to the specific repositories.

## Rate Limits

| Auth type | Requests per hour |
|---|---|
| Authenticated (PAT) | 5000 |
| Unauthenticated | 60 |
| GitHub App | 15000 |

git-branch-dashboard uses authenticated requests only.

## Troubleshooting

**401 Unauthorized** - The token is invalid or expired. Generate a new token at `https://github.com/settings/tokens` and update it with `git-branch-dash config set github-token ghp_...`.

**403 Forbidden** - The token does not have the required scope. Verify it has at minimum `read:repo` for public repos or `repo` for private repos.

**404 Not Found** - The owner or repo slug is incorrect. Check the repository settings in the dashboard under Repositories.

**PRs not appearing on branches** - Verify the `branch_name` in `PRRecord` matches the branch `name` exactly (case-sensitive). Check that a scan has run after the PR was opened.

**Secondary rate limit (429)** - This happens when making too many requests in a short window. Add a delay between repo scans or reduce the scan interval.