github-api (also known as Github.js) is a higher-level JavaScript wrapper for the GitHub API. It provides a more convenient, object-oriented interface over raw HTTP requests. The library, currently at version 3.4.0, offers dual support for both traditional callback-based APIs (as seen in versions prior to 1.0) and modern Promise-based APIs, with the latter returning raw Axios request promises for greater flexibility. Its release cadence is driven by bug fixes, new API feature implementations (like `getCombinedStatus` and `listCommitsOnPR`), and crucial security updates. It aims to abstract the complexities of direct GitHub API interactions while remaining compatible with both Node.js (LTS and current versions) and browser environments, offering a key differentiator through its flexible API consumption patterns and direct Axios promise exposure.
npm install github-apiVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to instantiate the GitHub client, authenticate with a personal access token, create and read a public gist, and list the authenticated user's repositories using the modern Promise-based API with async/await. It includes error handling and highlights the use of environment variables for sensitive credentials.
Review API documentation for specific methods. Transition from raw callbacks to `.then().catch()` or `async/await` for most operations. Be prepared to handle Axios response objects directly, as method calls now return raw promises containing `{ data, status, headers, config }`.Upgrade to `github-api@3.2.1` or `github-api@3.4.0` (or the latest stable version) immediately. Ensure your `package.json` specifies a secure version range for `github-api` and `axios`.
Consistently use either callbacks or promises for API calls within your codebase. When using promises, always handle the `{ data }` object from the Axios response: `someMethod().then(({ data }) => { /* use data */ })`.Always initialize `GitHub` with appropriate authentication: `new GitHub({ token: 'YOUR_PAT' })`. Ensure your Personal Access Token (PAT) has the necessary scopes for the operations you are performing. Avoid hardcoding credentials; use environment variables or a secure configuration management system.Monitor the project's GitHub repository for updates on maintainership. Consider contributing or preparing for alternative GitHub API clients in the long term, such as Octokit.js, which is officially maintained by GitHub.
Ensure your `GitHub` instance is initialized with a Personal Access Token (PAT): `new GitHub({ token: 'YOUR_PAT' })`. Verify that the PAT has the required scopes (permissions) for the specific API call you are making.Confirm the method you are calling is indeed promise-based. If it's callback-based, pass a callback function. If it's promise-based, ensure the `GitHub` object and its service methods are correctly instantiated before calling methods on them.
Check the `x-ratelimit-remaining` and `x-ratelimit-reset` headers in the response for rate limit information and wait until the reset time. Review your PAT's scopes to ensure it has all necessary permissions for the operation. If persistently blocked, consider using GitHub Apps for higher rate limits or more granular permissions.
For CommonJS, use `const GitHub = require('github-api');`. For ES Modules, ensure your project is configured for ESM (`"type": "module"` in `package.json`) and use `import GitHub from 'github-api';`.