ghutils

A collection of utility functions for dealing with the GitHub API


Used by:

* ghissues - a Node.js library to interact with the GitHub Issues API
* ghpulls - a Node.js library to interact with the GitHub Pull Request API
* ghrepos - a Node.js library to interact with the GitHub Repos API
* ghusers - a Node.js library to interact with the GitHub Users API
* ghteams - a Node.js library to interact with the GitHub Teams API
* ghreleases - a Node.js library to interact with the GitHub Releases API

Requirements

- Node.js >= 20

Example

``js
import { ghget, lister } from 'ghutils'

const auth = { token: 'your-github-token' }

// Make a single GET request
const { data } = await ghget(auth, 'https://api.github.com/user')
console.log(data)

// List all items from a paginated endpoint
const issues = await lister(auth, 'https://api.github.com/repos/owner/repo/issues')
console.log(issues)
`

API

All methods return Promises and use native fetch internally.

$3

The API root URL: 'https://api.github.com'

$3

Helper to build request options with proper headers. Accepts a GitHub auth object from ghauth (containing a token property) and optional additional options.

$3

Make a GitHub API compatible GET request to the given URL. Returns { data, res } where data is the parsed JSON response and res is the fetch Response object.

`js
const { data, res } = await ghget(auth, 'https://api.github.com/user')
`

$3

Make a GitHub API compatible POST request with JSON body.

`js
const { data } = await ghpost(auth, 'https://api.github.com/repos/owner/repo/issues', {
title: 'New issue',
body: 'Issue description'
})
`

$3

Make a GitHub API compatible PATCH request with JSON body.

`js
const { data } = await ghpatch(auth, 'https://api.github.com/repos/owner/repo/issues/1', {
state: 'closed'
})
`

$3

Make a GitHub API compatible DELETE request.

`js
await ghdelete(auth, 'https://api.github.com/repos/owner/repo/issues/1/labels/bug')
`

$3

Given a paginated URL resource, recursively fetch all available pages of data and return an array containing the complete list.

Options:
- afterDate - A Date object; only return items with created_at after this date
- Any other options are passed as query parameters (e.g., state, per_page)

`js
// Get all open issues
const issues = await lister(auth, 'https://api.github.com/repos/owner/repo/issues', {
state: 'open',
per_page: 100
})

// Get issues created after a specific date
const recentIssues = await lister(auth, 'https://api.github.com/repos/owner/repo/issues', {
afterDate: new Date('2024-01-01')
})
`

Authentication

All methods accept an auth object with a token property. Use ghauth to create and manage persistent GitHub authentication tokens for command-line apps:

`js
import ghauth from 'ghauth'

const auth = await ghauth({
configName: 'my-app',
clientId: 'your-github-oauth-app-client-id',
scopes: ['repo']
})
// auth = { token: 'ghp_xxxxxxxxxxxx', user: 'username' }
`

Or provide the token directly:

`js
const auth = { token: 'ghp_xxxxxxxxxxxx' }
`

For backwards compatibility with older versions, an object with both user and token properties is also accepted (the user` property is ignored).

License & Copyright

ghutils is Copyright (c) 2015-2025 Rod Vagg @rvagg and licensed under the MIT licence. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE.md file for more details.