{"id":16659,"library":"octokit-auth-netrc","title":"Octokit Netrc Authentication Plugin","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/travi/octokit-auth-netrc","tags":["javascript"],"install":[{"cmd":"npm install octokit-auth-netrc","lang":"bash","label":"npm"},{"cmd":"yarn add octokit-auth-netrc","lang":"bash","label":"yarn"},{"cmd":"pnpm add octokit-auth-netrc","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is an authentication plugin for Octokit, requiring an Octokit instance to function.","package":"@octokit/core","optional":false}],"imports":[{"note":"The package became ESM-only starting with v3.0.0. CommonJS `require` is no longer supported.","wrong":"const createNetrcAuth = require('octokit-auth-netrc').createNetrcAuth;","symbol":"createNetrcAuth","correct":"import { createNetrcAuth } from 'octokit-auth-netrc';"},{"note":"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.","symbol":"AuthFunction","correct":"import { AuthFunction } from '@octokit/auth-token';"},{"note":"For GitHub Enterprise Server, explicitly pass the `domain` option to `createNetrcAuth`.","symbol":"createNetrcAuth (GHES)","correct":"import { createNetrcAuth } from 'octokit-auth-netrc';\nconst enterpriseAuth = createNetrcAuth({ domain: 'github.acme-inc.com' });"}],"quickstart":{"code":"import { Octokit } from '@octokit/core';\nimport { createNetrcAuth } from 'octokit-auth-netrc';\n\nasync function authenticateAndFetchUser(domain = 'api.github.com') {\n  try {\n    const auth = createNetrcAuth({ domain });\n    const authResult = await auth();\n    console.log(`Successfully authenticated to ${domain} using .netrc file.`);\n\n    const octokit = new Octokit({\n      authStrategy: createNetrcAuth,\n      auth: { domain }\n    });\n\n    const { data: user } = await octokit.request('GET /user');\n    console.log(`Authenticated as: ${user.login} (${user.id}) on ${domain}`);\n  } catch (error) {\n    if (error.code === 'ENONETRCTOKEN') {\n      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`);\n    } else {\n      console.error(`Authentication failed for ${domain}:`, error.message);\n    }\n  }\n}\n\n(async () => {\n  console.log('Attempting authentication for api.github.com...');\n  await authenticateAndFetchUser('api.github.com');\n\n  // Example for GitHub Enterprise Server (replace with your actual domain)\n  // console.log('\\nAttempting authentication for github.acme-inc.com...');\n  // await authenticateAndFetchUser('github.acme-inc.com');\n})();","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js runtime to version `^20.19.0` or `>=22.14.0`.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"Starting with version 3.0.0, `octokit-auth-netrc` is an ESM-only package. It no longer supports CommonJS `require()` syntax.","severity":"breaking","affected_versions":">=3.0.0"},{"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+).","message":"Version 3.0.0 dropped support for Node.js versions 14 and 16.","severity":"breaking","affected_versions":">=3.0.0 <4.0.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":">=3.1.2"},{"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>`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Convert your project or file to ESM using `import` statements and ensure your `package.json` has `\"type\": \"module\"` or use `.mjs` file extensions.","cause":"Attempting to use `require()` to import `octokit-auth-netrc` in a CommonJS environment, but the package is ESM-only since v3.0.0.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../octokit-auth-netrc/lib/index.js from ... not supported."},{"fix":"Add an entry to your `~/.netrc` file similar to:\n```\nmachine api.github.com\n  login YOUR_GITHUB_PERSONAL_ACCESS_TOKEN\n```\nMake sure the file permissions are correct (e.g., `chmod 600 ~/.netrc`).","cause":"The `.netrc` file does not contain a machine entry for `api.github.com` (or the specified domain) with a `login` field.","error":"Error: ENONETRCTOKEN: Token for api.github.com not found in ~/.netrc"},{"fix":"When initializing `Octokit`, pass the `createNetrcAuth` function as `authStrategy`, and its options as `auth`:\n```typescript\nconst octokit = new Octokit({\n  authStrategy: createNetrcAuth,\n  auth: { domain: 'github.acme-inc.com' }\n});\n```","cause":"Incorrectly passing the result of `createNetrcAuth()` directly as `authStrategy` to `new Octokit()`, rather than the `createNetrcAuth` function itself.","error":"Error: Auth strategy must be a function or have an 'auth' method. Received: [object Object]"}],"ecosystem":"npm"}