Octokit Netrc Authentication Plugin

Common errors

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

  cause 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

  cause 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]

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

Warnings

• breaking Version 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`.
• breaking Starting 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.
• breaking Version 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+).
• gotcha In 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.
• gotcha The `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>`.

Install

• npm install octokit-auth-netrc npm
• yarn add octokit-auth-netrc yarn
• pnpm add octokit-auth-netrc pnpm

Imports

• createNetrcAuth
  wrong:

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

  correct:

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

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

Quickstart

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