Registry / http-networking / octokit-from-auth

octokit-from-auth

library0.3.2jsnpmunverified

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.

http-networking auth-security devops

npm install octokit-from-auth

github ↗package ↗

INSTALL

IMPORT

SIG · OCTOKIT-FROM-AUTH

octokit-from-auth

http-networkingjavascriptv0.3.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

octokitFromAuth

✓ import { octokitFromAuth } from 'octokit-from-auth';

✗ const { octokitFromAuth } = require('octokit-from-auth');

Package is ESM-only; CommonJS `require` will fail. Use named imports for functions.

octokitFromAuthSafe

✓ import { octokitFromAuthSafe } from 'octokit-from-auth';

✗ 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

✓ import { Octokit } from '@octokit/core';

✗ import { Octokit } from 'octokit-from-auth';

While octokit-from-auth returns an Octokit instance, the `Octokit` type itself comes from `@octokit/core`, which is a peer/transitive dependency.

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();

Debug

Known issues

gotchaThe `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.

affects: >=0.1.0

breakingThis 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.

affects: >=0.1.0

breakingThe 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.

affects: >=0.3.2

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/octokit-from-auth/dist/index.js from .../my-script.js not supported.

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.

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' })`.

Upgrade

Version history

0.3.2latest on npm

Audit

Dependencies

octokitrequiredCore dependency for creating GitHub API clients.

get-github-auth-tokenrequiredUsed internally to resolve authentication tokens from environment variables or `gh auth token` CLI.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/JoshuaKGoldberg/octokit-from-auth ↗

packagehttps://www.npmjs.com/package/octokit-from-auth ↗