Registry / http-networking / octokit-auth-netrc

octokit-auth-netrc

library4.0.0jsnpmunverified

The `octokit-auth-netrc` package provides a plugin for Octokit that enables authentication using credentials stored in a user's `.netrc` file. This is particularly useful for command-line tools and scripts that need to interact with GitHub without hardcoding tokens or using environment variables directly. The current stable version is 4.0.0, which was released on January 30, 2026. This library's release cadence is generally tied to updates in the Octokit ecosystem and Node.js LTS version changes. Its key differentiator is simplifying authentication against GitHub (including GitHub Enterprise Server) by leveraging the standard `.netrc` file format, providing a robust and familiar mechanism for developers who already use this method for other tools like `curl`. It handles both `api.github.com` and custom GitHub Enterprise domains.

http-networking auth-security devops

npm install octokit-auth-netrc

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OCTOKIT-AUTH-NETRC

octokit-auth-netrc

http-networkingjavascriptv4.0.0

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.

createNetrcAuth

✓ import { createNetrcAuth } from 'octokit-auth-netrc';

✗ const createNetrcAuth = require('octokit-auth-netrc').createNetrcAuth;

The package became ESM-only starting with v3.0.0. CommonJS `require` is no longer supported.

AuthFunction

✓ import { AuthFunction } from '@octokit/auth-token';

While not directly exported by this package, the `auth()` function returned by `createNetrcAuth` adheres to the `@octokit/auth-token`'s `AuthFunction` interface for type compatibility.

createNetrcAuth (GHES)

✓ import { createNetrcAuth } from 'octokit-auth-netrc'; const enterpriseAuth = createNetrcAuth({ domain: 'github.acme-inc.com' });

For GitHub Enterprise Server, explicitly pass the `domain` option to `createNetrcAuth`.

This quickstart demonstrates how to authenticate with GitHub using `octokit-auth-netrc` and then make a simple API request to fetch the authenticated user's details, including handling for a missing .netrc entry.

import { Octokit } from '@octokit/core'; import { createNetrcAuth } from 'octokit-auth-netrc'; async function authenticateAndFetchUser(domain = 'api.github.com') { try { const auth = createNetrcAuth({ domain }); const authResult = await auth(); console.log(`Successfully authenticated to ${domain} using .netrc file.`); const octokit = new Octokit({ authStrategy: createNetrcAuth, auth: { domain } }); const { data: user } = await octokit.request('GET /user'); console.log(`Authenticated as: ${user.login} (${user.id}) on ${domain}`); } catch (error) { if (error.code === 'ENONETRCTOKEN') { console.error(`Error: No token found in .netrc for ${domain}. Please add an entry like:\n\nmachine ${domain}\n login <your_personal_access_token>\n`); } else { console.error(`Authentication failed for ${domain}:`, error.message); } } } (async () => { console.log('Attempting authentication for api.github.com...'); await authenticateAndFetchUser('api.github.com'); // Example for GitHub Enterprise Server (replace with your actual domain) // console.log('\nAttempting authentication for github.acme-inc.com...'); // await authenticateAndFetchUser('github.acme-inc.com'); })();

Debug

Known issues

breakingVersion 4.0.0 of `octokit-auth-netrc` dropped official support for Node.js versions 18 and 21. Users should upgrade to Node.js v20.19.0 or >=22.14.0.

fix

Upgrade your Node.js runtime to version `^20.19.0` or `>=22.14.0`.

affects: >=4.0.0

breakingStarting with version 3.0.0, `octokit-auth-netrc` is an ESM-only package. It no longer supports CommonJS `require()` syntax.

fix

Migrate your codebase to use ES module `import` statements. Ensure your `package.json` specifies `"type": "module"` or use `.mjs` file extensions for ESM files.

affects: >=3.0.0

breakingVersion 3.0.0 dropped support for Node.js versions 14 and 16.

fix

Upgrade your Node.js runtime to version 18, 20, or newer (up to v21 for pre-v4, then v20.19.0 or >=22.14.0 for v4+).

affects: >=3.0.0 <4.0.0

gotchaIn version 3.1.2, the internal `netrc` dependency was replaced with a fork under the `@travi` scope. While this was a bug fix, it indicates a dependency change that might affect very specific edge cases or users interacting directly with the underlying `netrc` parsing logic (though unlikely for typical usage).

fix

No direct fix required for typical usage, but be aware of the internal dependency change if experiencing unexpected parsing behavior of the `.netrc` file.

affects: >=3.1.2

gotchaThe `createNetrcAuth` function will throw an error with code `ENONETRCTOKEN` if it cannot find a corresponding entry for the specified domain (defaults to `api.github.com`) in the `~/.netrc` file.

fix

Ensure your `~/.netrc` file contains an entry for the target domain (e.g., `api.github.com` or your GitHub Enterprise Server domain) formatted correctly, including `machine <domain>` and `login <personal access token>`.

affects: >=2.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module .../octokit-auth-netrc/lib/index.js from ... not supported.

Attempting to use `require()` to import `octokit-auth-netrc` in a CommonJS environment, but the package is ESM-only since v3.0.0.

fix

Convert your project or file to ESM using `import` statements and ensure your `package.json` has `"type": "module"` or use `.mjs` file extensions.

Error: ENONETRCTOKEN: Token for api.github.com not found in ~/.netrc

The `.netrc` file does not contain a machine entry for `api.github.com` (or the specified domain) with a `login` field.

fix

Add an entry to your `~/.netrc` file similar to:
```
machine api.github.com
  login YOUR_GITHUB_PERSONAL_ACCESS_TOKEN
```
Make sure the file permissions are correct (e.g., `chmod 600 ~/.netrc`).

Error: Auth strategy must be a function or have an 'auth' method. Received: [object Object]

Incorrectly passing the result of `createNetrcAuth()` directly as `authStrategy` to `new Octokit()`, rather than the `createNetrcAuth` function itself.

fix

When initializing `Octokit`, pass the `createNetrcAuth` function as `authStrategy`, and its options as `auth`:
```typescript
const octokit = new Octokit({
  authStrategy: createNetrcAuth,
  auth: { domain: 'github.acme-inc.com' }
});
```

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

@octokit/corerequiredThis is an authentication plugin for Octokit, requiring an Octokit instance to function.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/travi/octokit-auth-netrc ↗

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

homepagehttps://npm.im/octokit-auth-netrc ↗