How to Display Private Repository Statistics in GitHub Readme Stats

To display private repository statistics in GitHub Readme Stats, you must deploy a self-hosted instance and configure a GitHub Personal Access Token with repo scope, as the public server only accesses public repositories.

GitHub Readme Stats by anuraghazra is a popular tool for generating dynamic statistics cards, but accessing private repository data requires specific authentication. By default, the public Vercel deployment can only fetch metrics from public repositories. To include stars, commits, and pull requests from your private repositories, you need to run your own instance with a properly scoped token.

Why You Need a Self-Hosted Instance for Private Repos

The public github-readme-stats server operates without authentication tokens for security reasons, limiting it to public repository data only. When you deploy your own instance, you can securely store a GitHub Personal Access Token (PAT) in environment variables, granting the service permission to read your private repositories. This architecture ensures that sensitive repository data never passes through third-party servers you don't control.

Step-by-Step Setup for Private Repository Access

1. Deploy Your Own Instance

Follow the "Deploy on your own" instructions in the repository's readme.md (see lines 120 and 465). You can deploy to Vercel, Netlify, or Docker. This creates a personal endpoint under your control.

2. Configure the Personal Access Token (PAT)

Create a GitHub token with the repo scope and add it as an environment variable named PAT_1 in your deployment settings. The code in src/common/error.js explicitly validates this variable, throwing an error if PAT_1 is missing at line 15. You can add multiple tokens as PAT_2, PAT_3, etc., to handle rate limiting.

3. Verify Token Rotation and Error Handling

The retry mechanism in src/common/retryer.js (lines 8-16) cycles through all PAT_* environment variables, attempting each token until one succeeds. This ensures high availability if one token hits rate limits or expires.

How the Token Authentication Works Under the Hood

When requesting repository statistics, the fetcher in src/fetchers/repo.js constructs a GraphQL query and includes your token in the Authorization: token ... header at line 51. The response includes an isPrivate flag, which the code checks at lines 92-104. If the repository is private and a valid token is supplied, the data merges into the response; otherwise, the service throws a MissingParamError.

Code Example: Embedding a Private Repo Card

Use your self-hosted instance URL instead of the public endpoint:

<!-- Request stats from your deployed instance -->
[![Private Repo Stats](
  https://my-stats-instance.vercel.app/api?username=YOUR_USER&repo=PRIVATE_REPO&show_icons=true
)](https://github.com/YOUR_USER/PRIVATE_REPO)

For the general stats card aggregating all repositories, omit the repo parameter. The service will include private repositories that your token can access in the total commit and star counts.

Summary

• The public github-readme-stats server cannot access private repositories due to missing authentication.
• Deploy a self-hosted instance to securely store your GitHub credentials.
• Set the PAT_1 environment variable with a token possessing the repo scope.
• The service automatically rotates through multiple tokens (PAT_1, PAT_2, etc.) using the retryer logic in src/common/retryer.js.
• Private repository data is fetched via src/fetchers/repo.js and only returned when proper authentication is present.

Frequently Asked Questions

Can I display private stats without self-hosting?

No. According to the source code and repository documentation, the public server intentionally lacks authentication tokens to prevent abuse. Private repository statistics require a Personal Access Token, which must remain secure in your own deployment environment as specified in readme.md at lines 120 and 465.

What permissions does my GitHub token need?

You must grant the repo scope to your Personal Access Token. This scope provides read access to code, commits, and metadata in private repositories. Without this scope, src/fetchers/repo.js cannot retrieve the private flag or associated statistics, resulting in authentication errors.

How do I handle multiple private repositories or organizations?

Configure additional environment variables named PAT_2, PAT_3, and so on. The retryer system in src/common/retryer.js iterates through all PAT_* variables, allowing you to distribute API calls across multiple tokens or access repositories across different organizational accounts.

What happens if my token expires or is invalid?

If PAT_1 is missing entirely, src/common/error.js throws a specific error at line 15. If the token is invalid or expired during a request, the GraphQL fetcher in src/fetchers/repo.js returns an authentication error, and the retryer attempts the next available token in your configuration until all options are exhausted.

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