Personal Access Token

Personal Access Tokens (PATs)

A Personal Access Token (PAT) is used to authenticate with GitHub in place of a password — for example, when pulling private packages, publishing packages, or using the GitHub API from scripts and CI/CD pipelines.

GitHub offers two types of PATs:

Token Types

Fine-grained Tokens (recommended for most tasks)

Fine-grained tokens are the newer, more secure token format introduced by GitHub. They offer:

• Repository-scoped access — you select exactly which repositories the token can access, rather than granting access to everything.
• Granular permissions — instead of broad scopes (e.g. repo), you choose specific read/write permissions per resource (Issues, Pull Requests, Contents, etc.).
• Expiry enforcement — fine-grained tokens require an expiry date (maximum 1 year).
• Owner approval — if your organisation enforces it, tokens may require admin approval before they become active.

Fine-grained tokens are ideal for:

• Accessing or cloning specific repositories
• Operating GitHub Actions with least-privilege access
• Anything where limiting blast radius is important

Limitation: Fine-grained tokens cannot currently authenticate against the GitHub Packages / npm registry. If your task involves installing or publishing packages, you must use a Classic token.

Classic Tokens (required for GitHub Packages)

Classic tokens use a broad, scope-based permission model and have been available since GitHub's early API days. While less granular than fine-grained tokens, they are currently the only supported token type for GitHub Packages authentication.

When you must use a Classic token

Required scopes for package work

When creating a Classic token for package consumption or development, select the following scopes:

Tip: If you only need to consume (install) packages and not publish them, read:packages + repo is sufficient. Only add write:packages if you are actively developing and publishing packages.

How to Create a Classic Token

This is the token type you will need for local development and CI/CD package access.

1. Go to GitHub Tokens (Classic) — ensure you are logged into the correct account.
2. Give the token a descriptive Note, e.g. Package Development or Package Read-Only.
3. Set an Expiration — choose an appropriate window (e.g. 90 days). Avoid "No expiration" for security reasons.
4. Under Select scopes, tick the scopes relevant to your use case (see table above).
5. Click Generate token and copy it immediately — GitHub will not show it again.

How to Create a Fine-grained Token

1. Go to GitHub Fine-grained Tokens — ensure you are logged into the correct account.
2. Give the token a descriptive Token name.
3. Set an Expiration (required — up to 365 days).
4. Under Resource owner, select the organisation or your personal account.
5. Under Repository access, choose Only select repositories and pick the repositories needed.
6. Under Permissions, expand each section and set only the minimum permissions required.
7. Click Generate token and copy it immediately.

Configuring projects to use tokens

This setup works for both local development and CI/CD pipelines.

1. Configure projects to use tokens in the .npmrc or .yarnrc.yml files.
2. Set the NODE_AUTH_TOKEN environment variable to your Classic token when applicable in:
   • GitHub Repository Secrets for CI/CD pipelines
   • User Account System environment variables for local development.

1. For Yarn Projects

Once you have a Classic token, configure npm to authenticate against the GitHub Package Registry by adding the following to the project-level .yarnrc.yml:

npmScopes:
  es-profiler:
    npmAlwaysAuth: false
    npmAuthToken: ${NODE_AUTH_TOKEN:-}
    npmRegistryServer: "https://npm.pkg.github.com"

1. For NPM Projects

Once you have a Classic token, configure npm to authenticate against the GitHub Package Registry by adding the following to the project-level .npmrc:

//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
@es-profiler:registry=https://npm.pkg.github.com

2. For Local Development

Never commit your token to source control. Use environment variables or secrets management instead. In CI/CD pipelines, store the token as a secret (e.g. GITHUB_TOKEN or a custom secret) and reference it in your npmrc via ${TOKEN_ENV_VAR}.

Best Practices

• Rotate tokens regularly — set a calendar reminder before your token expires.
• Use the minimum required scopes — avoid repo on Classic tokens unless the package repository is private.
• Revoke unused tokens — audit your tokens periodically at github.com/settings/tokens.
• Never share tokens — each developer and each CI/CD pipeline should have its own token.
• Prefer fine-grained tokens for any non-package GitHub API usage.