Gh Issue Tracker

Error Tracker Installation Skill

Install and configure gh-issue-tracker — a lightweight error tracking package that creates GitHub Issues instead of sending to SaaS platforms.

Quick Reference

npm install gh-issue-tracker   # or pnpm add / yarn add

Required env vars: GITHUB_TOKEN, GITHUB_REPO

Prerequisites

1. GitHub Fine-Grained Personal Access Token with:
   • Repository access: target repository only
   • Permissions: Issues (read/write)
   • Generate at: GitHub → Settings → Developer settings → Fine-grained tokens
2. Node.js >= 20 (uses Web Crypto)

Step 1: Determine the Architecture

ASK THE USER which errors they need to capture. This determines the architecture:

Option A: Server-Only Errors

Best for: APIs, backend services, CLI tools, scripts, workers.

Server error → captureException() → GitHub Issues API

• gh-issue-tracker runs server-side only
• GITHUB_TOKEN stays in server environment
• Simplest setup: just init() + captureException()

Option B: Server + Client Errors (Recommended for web apps)

Best for: Next.js, React, or any web app with a server component.

Browser error → POST to proxy endpoint → captureException() → GitHub Issues API
Server error  → captureException() directly → GitHub Issues API

• gh-issue-tracker still runs server-side only
• Browser errors are reported via a proxy endpoint (API route)
• GITHUB_TOKEN NEVER reaches the browser
• Error boundaries in React catch client-side errors and POST to the proxy

Security Guidance

The package is server-side only (token stays off the client) — it cannot be imported in browser code.

The token risk depends on your setup:

• Fine-grained PAT with Issues-only on a public repo: Low risk. Someone with the token can create/close issues — same as anyone can do via the GitHub UI on a public repo.
• Classic token with repo scope or private repo: Higher risk. Use the proxy pattern to keep the token isolated.

Proxy pattern (recommended for private repos or maximum security):

1. Error boundaries send error details (message, stack, URL) to a proxy endpoint
2. The proxy validates the request and calls captureException() server-side
3. The GitHub token lives only in the proxy's environment

Step 2: Install the package

npm install gh-issue-tracker

(Use the project's package manager: pnpm, yarn, or npm)

Step 3: Set environment variables

Add to .env (or .env.local for Next.js):

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
GITHUB_REPO=myorg/myapp

Ensure .env is in .gitignore. For production, set these via your hosting platform (Vercel, Railway, etc.).

For Option B (client + server), also set:

ALLOWED_ORIGINS=https://myapp.com,https://staging.myapp.com

Step 4: Framework-Specific Setup

Next.js App Router

Server-side initialization (both Option A and B)

Create instrumentation.ts at project root:

import { init as initErrorTracker, captureException, flush } from 'gh-issue-tracker'

export async function register() {
  initErrorTracker({
    githubToken: process.env['GITHUB_TOKEN'] ?? '',
    githubRepo: process.env['GITHUB_REPO'] ?? '',
    environment: process.env['NODE_ENV'] ?? 'development',
    enabled: !!process.env['GITHUB_TOKEN'],
    labels: ['my-app'],
  })
}

export async function onRequestError(error: unknown) {
  if (error instanceof Error) {
    captureException(error, { tags: { source: 'onRequestError' } })
  } else {
    captureException(new Error(String(error)), { tags: { source: 'onRequestError' } })
  }
  await flush()
}

See https://github.com/zot24/gh-issue-tracker/tree/main/examples/nextjs-instrumentation/` for a complete file with inline comments.

Client error capture (Option B only)

Step 4a: Create the proxy endpoint

Create app/api/errors/capture/route.ts — this is the server-side endpoint that receives browser errors and forwards them to GitHub.

Copy from https://github.com/zot24/gh-issue-tracker/tree/main/examples/nextjs-error-proxy/route.ts`. Key security features:

• Origin allowlist (ALLOWED_ORIGINS env var)
• IP-based rate limiting (5 req/hour per IP)
• Zod schema validation
• 10KB body size cap
• Returns 200 OK for invalid requests (doesn't leak validation logic)

Step 4b: Create error boundaries

Create app/error.tsx and app/global-error.tsx — these are React components that catch runtime errors in the browser and POST to the proxy.

Copy from https://github.com/zot24/gh-issue-tracker/tree/main/examples/nextjs-error-boundaries/`. These components:

• Catch errors via Next.js error boundary mechanism
• POST { message, stack, digest, url, boundary } to /api/errors/capture
• Display a user-friendly error page with "Try again" button
• Fire-and-forget (.catch(() => {})) — error reporting failure doesn't affect UX

Express / Node.js (Option A)

import { init, captureException, flush } from 'gh-issue-tracker'

// At app startup
init({
  githubToken: process.env['GITHUB_TOKEN']!,
  githubRepo: process.env['GITHUB_REPO']!,
  environment: process.env['NODE_ENV'] ?? 'development',
  labels: ['my-app'],
})

// Error handler middleware (MUST be after all routes)
app.use((err, req, res, next) => {
  captureException(err instanceof Error ? err : new Error(String(err)), {
    requestUrl: req.originalUrl,
    tags: { method: req.method },
  })
  flush().finally(() => res.status(500).json({ error: 'Internal server error' }))
})

See https://github.com/zot24/gh-issue-tracker/tree/main/examples/express-middleware/` for a complete example.

Generic Node.js (Option A — scripts, workers, etc.)

import { init, captureException, flush } from 'gh-issue-tracker'

init({
  githubToken: process.env['GITHUB_TOKEN']!,
  githubRepo: process.env['GITHUB_REPO']!,
})

try {
  // your code
} catch (error) {
  captureException(error instanceof Error ? error : new Error(String(error)))
  await flush()
}

Step 5: Verify

1. Start the application
2. Trigger a test error (server-side or client-side depending on your architecture)
3. Check the GitHub repository's Issues tab
4. Look for an issue with the error-report label
5. Trigger the same error again — verify it adds a thumbs-up reaction, not a duplicate issue

Configuration Options

captureBugReport({ screenshot }) needs Issues write only. No Contents permission, no APP_BASE_URL, no proxy route.

Security Recommendations

• Use a fine-grained PAT scoped to Issues only on a single repo
• Don't prefix the token with NEXT_PUBLIC_ or VITE_ (these expose to browser bundles)
• .env files are in .gitignore
• If using a proxy, add origin allowlist + rate limiting
• For private repos, use the proxy pattern to isolate the token

Common Issues