gh-got

12.0.0 verified Sat Apr 25 auth: no javascript

Convenience wrapper for Got to interact with the GitHub API. Current stable version is 12.0.0 (requires Node.js 22). Release cadence is irregular with major versions often tied to Got updates. Key differentiators: automatic token handling via GITHUB_TOKEN env var, built-in rate limit info on responses/errors, supports GitHub Enterprise via prefixUrl. Pure ESM since v10, uses Got 15 internally. Consider @octokit/rest.js or @octokit/graphql.js unless already using Got.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause CommonJS require() called on ES module package.

fix

Use import statement instead of require(), or update Node.js to >=14 and use dynamic import.

error GotError: The prefix 'https://api.github.com/' must start with a valid URL prefix ↓

cause Invalid prefixUrl provided (e.g., missing trailing slash).

fix

Ensure prefixUrl ends with trailing slash, e.g., 'https://api.github.com/'.

error HTTPError: Response code 401 (Unauthorized) ↓

cause Missing or invalid GitHub token.

fix

Set GITHUB_TOKEN environment variable or pass token in options.context.token.

Warnings

breaking Starting from v10, package is pure ESM and requires Node.js 14+. ↓

fix Use import syntax instead of require(); update Node.js to >=14 (v12 requires Node.js 22).

breaking In v10, leading slashes in paths no longer work (e.g., '/users' fails). ↓

fix Remove leading slash: use 'users' instead of '/users'.

breaking v9 renamed the 'endpoint' option to 'baseUrl'. ↓

fix Replace 'endpoint' with 'baseUrl' in options.

breaking v12 requires Node.js 22 and updates Got to v15. ↓

fix Upgrade Node.js to >=22.

deprecated Package recommends using @octokit/rest.js or @octokit/graphql.js instead unless already using Got. ↓

fix Consider migrating to official GitHub SDKs for better features and support.

gotcha Authorization order: options.headers.authorization takes precedence over options.token, which falls back to GITHUB_TOKEN env var. ↓

fix Set token via context.token or GITHUB_TOKEN env var. Use options.headers.authorization for non-token auth (e.g., Bearer JWT).

Install

npm install gh-got

yarn add gh-got

pnpm add gh-got

Imports

ghGot
wrong
```
const ghGot = require('gh-got')
```
correct
```
import ghGot from 'gh-got'
```
Package is pure ESM since v10; CommonJS require() will throw an error.
ghGot
wrong
```
import { ghGot } from 'gh-got'
```
correct
```
import ghGot from 'gh-got'
```
gh-got has a default export only, not a named export.
response.rateLimit
```
const { rateLimit } = await ghGot('users/sindresorhus')
```
rateLimit is a property on the response object with { limit, remaining, reset }. Not available in stream API.

Quickstart

Demonstrates basic usage: import default, authenticate via token context, handle response and rate limit info.

import ghGot from 'gh-got';

async function main() {
  try {
    const { body, rateLimit } = await ghGot('users/sindresorhus', {
      context: {
        token: process.env.GITHUB_TOKEN ?? ''
      }
    });
    console.log(body.login);
    console.log('Rate limit remaining:', rateLimit.remaining);
  } catch (error) {
    console.error('GitHub API error:', error.message);
  }
}

main();