A collection of utility functions for dealing with the GitHub API
npm install ghutilsA 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
- Node.js >= 20
``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)
`
All methods return Promises and use native fetch internally.
The API root URL: 'https://api.github.com'
Helper to build request options with proper headers. Accepts a GitHub auth object from ghauth (containing a token property) and optional additional options.
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')
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'
})
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'
})
Make a GitHub API compatible DELETE request.
`js`
await ghdelete(auth, 'https://api.github.com/repos/owner/repo/issues/1/labels/bug')
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 datestate
- Any other options are passed as query parameters (e.g., , 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')
})
`
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).
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.