Complete Guide to Environment Variables for Self-Hosted GitHub Readme Stats

Self-hosted GitHub Readme Stats instances rely on environment variables defined primarily in src/common/envs.js to configure GitHub authentication, caching, feature toggles, and access control.

When deploying your own instance of the anuraghazra/github-readme-stats project, environment variables serve as the primary configuration mechanism. These variables control everything from GitHub API authentication to caching behavior and user access restrictions. This guide catalogs every environment variable available for self-hosted GitHub Readme Stats instances, referencing the exact source files where each is implemented.

General Runtime Configuration

The application respects standard Node.js conventions and Express server settings through these core variables.

NODE_ENV

Sets the Node environment (development, production, or test). This influences caching logic, logging verbosity, and test-mode behavior throughout the application.

PORT

Defines the HTTP port on which the Express server listens when running express.js. The code also checks for a lowercase port variant for flexibility.

# Docker example

docker run -e PORT=3000 -p 3000:3000 github-readme-stats

GitHub Authentication and Token Rotation

GitHub API rate limits require careful token management, implemented across src/common/retryer.js and helper scripts.

GITHUB_TOKEN

The primary Personal Access Token (PAT) used for all GitHub API calls, including stats, repos, gists, and pins. This is the fallback token used by scripts/helpers.js when individual PAT_N variables are exhausted.

PAT_1, PAT_2, … PAT_N

Additional rotating PATs that the internal retryer cycles through when rate-limit errors occur. The src/common/retryer.js implementation automatically falls back from PAT_1 to PAT_2 (and so on) when the GitHub API returns 403 or rate-limit status codes.

# Example .env configuration for token rotation

GITHUB_TOKEN=ghp_primary_token_here
PAT_1=ghp_backup_token_1
PAT_2=ghp_backup_token_2

Caching and Performance Controls

Fine-tune API response caching and data fetching behavior.

CACHE_SECONDS

Overrides the default cache TTL (time-to-live) in seconds for API responses. Set to 0 to disable caching entirely. This variable is read in src/common/cache.js and affects how long generated SVG cards are cached in memory or CDN edge nodes.

FETCH_MULTI_PAGE_STARS

When set to "true", the stats fetcher (src/fetchers/stats.js) paginates through all starred repositories to calculate total stars accurately. When "false" (default), it limits to the first page, conserving API rate limits for high-traffic instances.

Access Control and Filtering

Restrict which users and repositories can access your self-hosted instance via variables parsed in src/common/envs.js.

WHITELIST

Comma-separated list of GitHub usernames explicitly allowed to be displayed via the pin API. Requests for users not on this list return an error, preventing abuse of your GitHub token quota on public instances.

GIST_WHITELIST

Functions identically to WHITELIST but applies specifically to the Gist pin endpoint, allowing separate access control for gist embedding features.

EXCLUDE_REPO

Comma-separated list of repository full names (owner/repo) that the stats generator ignores when calculating language statistics and commit counts. Useful for excluding forks or automated repositories from your stats card.

# Example exclusion list

EXCLUDE_REPO=owner/repo1,owner/repo2,owner/automated-fork

Third-Party Service Integration

Connect external APIs for extended card functionality.

WAKATIME_API_TOKEN

Authentication token for the WakaTime API, required to generate WakaTime coding activity cards. The src/fetchers/wakatime.js file reads this token to authenticate requests to wakatime.com/api/v1.

TOP_LANGS_API_URL

Optional custom endpoint URL for the top-languages fetcher (src/fetchers/top-languages.js). This allows redirecting language statistics requests to an intermediate proxy or cached API layer instead of hitting GitHub directly.

CI/CD and Maintenance Script Configuration

Variables used by automation scripts in the /scripts directory for theme preview and repository maintenance.

DRY_RUN

When set to "true", script actions such as opening pull requests or posting comments are simulated without actual side effects. Used in scripts/preview-theme.js for safe testing of theme automation.

MOCK_PR_NUMBER

Allows preview scripts to pretend a specific PR number exists for testing purposes, overriding the actual GitHub API lookup in scripts/preview-theme.js.

COMMENTER

Overrides the GitHub username that automation scripts use when posting comments. Defined in scripts/helpers.js, this is useful when running bots under different service accounts.

REVIEWER

Specifies the GitHub username used for stale theme PR cleanup operations in scripts/close-stale-theme-prs.js.

STALE_DAYS

Number of days after which a theme PR is considered stale and eligible for automatic closure. Used by scripts/close-stale-theme-prs.js to determine cleanup thresholds.

Deployment-Specific Variables

VERCEL_PREVIEW_URL

URL of the Vercel preview deployment, used primarily by end-to-end tests in tests/e2e/e2e.test.js to validate card rendering against live preview instances.

Summary

• Authentication: Configure GITHUB_TOKEN and rotating PAT_N variables in src/common/retryer.js to handle GitHub API rate limits.
• Performance: Adjust CACHE_SECONDS and FETCH_MULTI_PAGE_STARS to balance data freshness against API quota consumption.
• Access Control: Use WHITELIST, GIST_WHITELIST, and EXCLUDE_REPO parsed in src/common/envs.js to restrict usage and filter repositories.
• Integrations: Set WAKATIME_API_TOKEN and TOP_LANGS_API_URL for external service connectivity.
• Maintenance: Leverage DRY_RUN, STALE_DAYS, and script-specific variables to automate theme management safely.

Frequently Asked Questions

What is the minimum required environment variable to run a self-hosted instance?

At minimum, you must provide a GITHUB_TOKEN environment variable containing a valid GitHub Personal Access Token. Without this token, the application cannot authenticate with the GitHub API to fetch user statistics, repository data, or language metrics. The token must have appropriate scopes for public repository access, or private scopes if you intend to display private contribution stats.

How do I configure multiple GitHub tokens for rate limit handling?

To implement token rotation and avoid hitting GitHub's rate limits, define your primary token as GITHUB_TOKEN and additional tokens as PAT_1, PAT_2, up to PAT_N. The retry logic in src/common/retryer.js automatically cycles through these tokens when it encounters rate limit errors, ensuring high availability for your self-hosted instance.

Can I disable caching or adjust the cache duration?

Yes, set the CACHE_SECONDS environment variable to override the default time-to-live for API responses. Setting CACHE_SECONDS=0 disables caching entirely, which is useful during development. For production deployments, higher values reduce GitHub API usage and improve response times. The caching logic is implemented in src/common/cache.js.

How do I restrict which GitHub users can use my self-hosted instance?

Use the WHITELIST environment variable to specify a comma-separated list of allowed GitHub usernames. For example: WHITELIST=user1,user2,user3. This prevents unauthorized users from consuming your API quota. Similarly, use GIST_WHITELIST to control access to the Gist pin endpoint specifically. These restrictions are parsed in src/common/envs.js.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}