# Complete Guide to Environment Variables for Self-Hosted GitHub Readme Stats > Discover all environment variables for self-hosted GitHub Readme Stats. Configure authentication, caching, and features for your instance. - Repository: [Anurag Hazra/github-readme-stats](https://github.com/anuraghazra/github-readme-stats) - Tags: api-reference - Published: 2026-02-28 --- **Self-hosted GitHub Readme Stats instances rely on environment variables defined primarily in [`src/common/envs.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/express.js). The code also checks for a lowercase `port` variant for flexibility. ```bash # 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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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. ```bash # 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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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. ```bash # 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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/scripts/preview-theme.js). ### COMMENTER Overrides the GitHub username that automation scripts use when posting comments. Defined in [`scripts/helpers.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/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`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/common/envs.js).