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
Requirements
Node.js >= 20
Example
import { ghget, lister } from 'ghutils'const auth = { token: 'your-github-token' }// Make a single GET requestconst { data } = await ghget(auth, 'https://api.github.com/user')console.log(data)// List all items from a paginated endpointconst 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.
apiRoot
The API root URL: 'https://api.github.com'
makeOptions(auth, options)
Helper to build request options with proper headers. Accepts a GitHub auth object from ghauth (containing a token property) and optional additional options.
ghget(auth, url, 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.
const { data, res } = await ghget(auth, 'https://api.github.com/user')
ghpost(auth, url, data, options)
Make a GitHub API compatible POST request with JSON body.
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)
// Get all open issuesconst issues = await lister(auth, 'https://api.github.com/repos/owner/repo/issues', { state: 'open', per_page: 100})// Get issues created after a specific dateconst 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:
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.
ghreleases - a Node.js library to interact with the GitHub Releases API