Octokit From Auth

0.3.2 · active · verified Wed Apr 22

octokit-from-auth simplifies the instantiation of a GitHub Octokit client, abstracting away the complexities of authentication token resolution. It automatically attempts to retrieve a token from `process.env.GH_TOKEN` or by executing `gh auth token` via the `get-github-auth-token` package. The library offers two functions: `octokitFromAuth`, which rejects if no token is found, and `octokitFromAuthSafe`, which resolves to an unauthenticated Octokit instance if no token is available. The current stable version is 0.3.2. Releases are consistent, primarily for dependency updates and minor fixes, with new features introduced in minor versions. It ships with TypeScript types and requires Node.js >=18.3.0. This package differentiates itself by offering a robust, opinionated, and flexible approach to Octokit instantiation and authentication, minimizing boilerplate for interacting with the GitHub API.

Common errors

```
Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/octokit-from-auth/dist/index.js from .../my-script.js not supported.
```
cause Attempting to `require()` an ESM-only package in a CommonJS module.

fix Convert your consuming script to an ES module by using `import` statements and ensuring your `package.json` specifies `"type": "module"` or by renaming your file to `.mjs`.
```
Error: No GitHub auth token could be found.
```
cause The `octokitFromAuth` function could not find an authentication token from `process.env.GH_TOKEN`, `gh auth token`, or the provided options.

fix Set the `GH_TOKEN` environment variable (e.g., `GH_TOKEN=gho_... node my-script.js`), or ensure the GitHub CLI (`gh`) is installed and authenticated, or explicitly pass an `auth` option to `octokitFromAuth({ auth: 'YOUR_TOKEN' })`.

Warnings

gotcha The `octokitFromAuth` function will throw an error if it cannot resolve an authentication token. If you need to proceed without authentication when a token is unavailable, use `octokitFromAuthSafe` instead.
Fix: Use `octokitFromAuthSafe` for scenarios where an unauthenticated Octokit is acceptable, or ensure `process.env.GH_TOKEN` is set or `gh auth token` is configured and available.
breaking This package is ESM-only and requires Node.js version 18.3.0 or higher. Attempting to use it in a CommonJS environment or with older Node.js versions will result in import errors.
Fix: Ensure your project uses `type: "module"` in `package.json` or uses `.mjs` files for ESM, and upgrade your Node.js runtime to `18.3.0` or newer.
breaking The underlying `octokit` dependency was updated to `v5` in version 0.3.2. While `octokit-from-auth` itself aims for API stability, direct interactions with the returned `Octokit` instance may be affected by breaking changes introduced in `octokit@v5`.
Fix: Consult the changelog for `@octokit/core` (or the specific Octokit package you use) for `v5` to understand potential breaking changes in the underlying API. Update any code directly calling Octokit methods or properties that might have changed.

Install

npm install octokit-from-auth npm
yarn add octokit-from-auth yarn
pnpm add octokit-from-auth pnpm

Imports

octokitFromAuth
wrong:
```
const { octokitFromAuth } = require('octokit-from-auth');
```
correct:
```
import { octokitFromAuth } from 'octokit-from-auth';
```
Package is ESM-only; CommonJS `require` will fail. Use named imports for functions.
octokitFromAuthSafe
wrong:
```
import octokitFromAuthSafe from 'octokit-from-auth';
```
correct:
```
import { octokitFromAuthSafe } from 'octokit-from-auth';
```
Use named imports; there is no default export. This function returns an unauthenticated Octokit if no token is found.
Octokit
wrong:
```
import { Octokit } from 'octokit-from-auth';
```
correct:
```
import { Octokit } from '@octokit/core';
```
While octokit-from-auth returns an Octokit instance, the `Octokit` type itself comes from `@octokit/core`, which is a peer/transitive dependency.

Quickstart

Demonstrates creating both authenticated and unauthenticated Octokit instances using `octokitFromAuth` and `octokitFromAuthSafe`, handling potential authentication failures gracefully.

import { octokitFromAuth, octokitFromAuthSafe } from 'octokit-from-auth';

async function run() {
  // Attempt to create an authenticated Octokit instance.
  // It will use process.env.GH_TOKEN or `gh auth token` if available.
  // This function will throw an error if no auth token is found.
  try {
    const authenticatedOctokit = await octokitFromAuth();
    const { data: user } = await authenticatedOctokit.request('GET /user');
    console.log(`Authenticated as ${user.login}.`);
  } catch (error) {
    console.warn(`Could not create authenticated Octokit: ${error.message}`);
    console.warn('Falling back to safe, unauthenticated Octokit...');

    // Create an Octokit instance that is unauthenticated if no token is found.
    const unauthenticatedOctokit = await octokitFromAuthSafe();
    const { data: publicUser } = await unauthenticatedOctokit.request('GET /users/{username}', {
      username: 'octokit',
    });
    console.log(`Accessed public user ${publicUser.login} without authentication.`);
  }
}

run();

view raw JSON →