[GitHubContributors] Badges render "invalid" for large repositories ("history or contributor list is too large") #12186

Are you experiencing an issue with...

shields.io

🐞 Description

When requesting a GitHub contributors badge for repositories with very large commit histories (such as NixOS/nixpkgs), the badge fails to render a contributor count. In the case of NixOS/nixpkgs:

The badge URL, parameters, and repository are all valid.

Reproducing Upstream API Behavior

1. Direct Authenticated GitHub CLI Call:
   Running an authenticated request against the contributors endpoint:

   gh api repos/NixOS/nixpkgs/contributors

   returns HTTP 403 Forbidden with the following payload:

   {
     "message": "The history or contributor list is too large to list contributors for this repository via the API.",
     "documentation_url": "https://docs.github.com/rest/repos/repos#list-repository-contributors",
     "status": "403"
   }

2. Pagination Does Not Bypass the Error:
   Attempting pagination or modifying page sizes (per_page=100, page=1) fails with the identical HTTP 403 response because GitHub's backend aborts the calculation before generating the first page.

3. Not a Rate Limit Failure:
   The request is authenticated and has ample rate limit quota remaining (x-ratelimit-remaining > 0). This error represents an intentional server-side computation safeguard for massive repositories on GitHub's REST API.

4. Control Experiment:
   Smaller repositories in the same organization work normally:

   gh api repos/NixOS/nixos/contributors --paginate --slurp | jq 'add | length'
   # Successfully returns contributor count

Current Shields Implementation

1. Request Execution (services/github/github-contributors.service.js):
   The service requests page 1 with per_page: '1' to extract the total count from the link header:

   const { res, buffer } = await this._request({
     url: `/repos/${user}/${repo}/contributors`,
     options: { searchParams: { page: '1', per_page: '1', anon: isAnon } },
     httpErrors: httpErrorsFor('repo not found'),
   })

2. Error Translation (services/github/github-helpers.js):
   httpErrorsFor only translates HTTP 404 and 422:

   function httpErrorsFor(notFoundMessage = 'repo not found') {
     return {
       404: notFoundMessage,
       422: notFoundMessage,
     }
   }

   Status 403 is unmapped.

3. Error Pipeline (core/base-service/check-error-response.js):
   When GitHub returns 403:

   • checkErrorResponse checks res.statusCode !== 200 and res.statusCode < 500.
   • Because httpErrors[403] is undefined, it instantiates an InvalidResponse exception with the fallback defaultPrettyMessage = 'invalid'.
   • BaseService._handleError() in core/base-service/base.js maps this to { isError: true, message: 'invalid', color: 'lightgray' }.

🔗 Link to the badge

• https://img.shields.io/github/contributors/NixOS/nixpkgs
• https://img.shields.io/github/contributors-anon/NixOS/nixpkgs

💡 Possible Solution

Displaying invalid is misleading to users because it suggests a malformed badge parameter or nonexistent repository rather than an upstream API size limit.

1. Could GithubContributors (or checkErrorResponse) inspect the response body for "The history or contributor list is too large" and render a more descriptive error badge (such as contributors | too large or contributors | not supported)?
2. Alternatively, is there any known fallback or alternative approach for obtaining contributor counts on large repositories where GitHub's REST endpoint is unavailable?