github-api

name	github-api
description	Fetch open pull requests and repository metadata from the GitHub REST API using Octokit

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

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:

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:

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:

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:

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:

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.