# committers.top ranks GitHub users by contributions per city

> The committers.top project is a Go command line tool that queries the GitHub GraphQL API, ranks users by contribution count for a set of preset locations, and publishes the result as a static site, and its own FAQ explains why the ranking is a two stage sort.

**ashkulz/committers.top** — CLI tool which uses the GitHub GraphQL API to rank users according to number of contributions, and corresponding static website.

- Repository: https://github.com/ashkulz/committers.top
- Website: https://committers.top
- Stars: 819 · Forks: 103
- Language: Go
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/ashkulz-committers-top

## Two sorts, because the API cannot sort by contributions

The most interesting thing in this project is explained in its FAQ rather than its feature list. The GitHub API does not allow sorting by contributions, so the tool sorts by number of followers first to get a larger list, and then sorts that list by contributions. The consequence is stated plainly: you need a minimum number of followers to appear on the list, and each page shows the minimum number of followers needed for that page. This is a real methodological compromise rather than a hidden detail, and any reader comparing two country pages is comparing two different follower thresholds. The tool is described as querying the GitHub GraphQL API for users and ranking them according to number of contributions, with several preset locations provided, and the whole project is a CLI plus a corresponding static website at committers.top. The audience is anyone curious about where open source activity is concentrated, and the ranking caveats are part of the tool rather than a bug in it.

## Running it needs a token and a preset location

The tool talks to the GitHub API, so it needs an access token with read:org and read:user permissions, which can be created in the GitHub token settings. The example invocation in the README shows the whole flag set.

```bash
go run *.go \
   --token paste-your-token-here \
   --preset worldwide \
   --amount 500 \
   --consider 1000 \
   --output csv \
   --file ./output.csv
```

The flags describe the shape of a run. The preset selects a location, worldwide in this example, amount is how many entries the output holds, and consider is how many candidates are fetched before the ranking is applied, so a consider value larger than the amount gives the ranker more to work with. The output format is a flag rather than a fixed behaviour, and csv with a file path is what the example uses. The repository layout suggests the internals are split by concern, with a github/ directory for the API access, a net/ directory for the network layer, a top/ directory for the ranking, an output/ directory, presets.go for the location definitions, and main.go at the root.

## A location is a free text query, which is why people go missing

The second reason someone might not appear on a list is geographic, and the mechanism is a design choice with consequences. The query is free text and not strictly geographical, so a user whose city is not in the query will not be picked up, and rural areas may be excluded in the same way. The FAQ offers a remedy that is really a workaround: adding the country name to your location on GitHub broadens the text that the query matches. That is a reasonable engineering answer to a text search, and it also means the boundaries of a city page are decided by whoever wrote the preset string. The third reason involves private commits. Those are included, the FAQ says, but they are no longer listed on the main country page, and they are moved to a subpage, and the README states the arrangement is done to favour open source contributions over private ones. So the headline number on a country page is public contributions only, and a full public plus private count is available on a subpage of each region page.

## Contribution counts differ from your profile, and here is the query to check

A third FAQ entry explains why the number on the site may not match the number on your own GitHub profile. The answer is about your own settings, since the profile displays either public contributions only or both public and private ones depending on configuration, while the site shows only public contributions by default, with the public plus private count on a subpage. The README then offers a way to see what the API actually returns for your account, using the GraphQL Explorer.

```bash
query { 
  viewer { 
    login
    contributionsCollection {
      restrictedContributionsCount
      contributionCalendar {
        totalContributions
      }
    }
  }
}
```

The restrictedContributionsCount field is the one that holds the private contribution total, which is the number the site is choosing not to show on its main pages. Running the query yourself is the fastest way to settle a disagreement about a specific count, and it is a good example of a project documenting its own data limitations rather than leaving people to guess.

## Adding a preset is a pull request with a scheduled workflow attached

The contribution guide treats a preset change as more than a one line edit, and the procedure is spelled out in full. When sending a pull request that changes only presets.go, you are asked to make sure that both your pull request branch and the gh-pages branch on your fork are up to date with upstream, with the explicit warning not to use the copy the master branch only option when forking. Then you go to the daily update workflow on your fork and trigger it via Run workflow with your pull request branch, which pushes a commit to the gh-pages branch, and you verify the changes look good. Finally you reference that commit in the pull request so the impact of merging is visible. The reason for the dance is that the website is built from a separate branch, so a change to the Go code is not visible on the site until the website branch is regenerated, and the reference commit is how the reviewer checks the rendered result. The README also asks that the provided pre-commit hooks be used and that go fmt, go vet and go lint be run liberally.

## A Go 1.17 module with a scratch based container image

The build setup is minimal, which fits a tool of this size. The go.mod names the module most-active-github-users-counter and declares Go 1.17, and the Dockerfile is a three stage build. The first stage pulls the CA certificates into an alpine image, the second builds the binary from a golang:1.17 image with CGO_ENABLED=0, and the third is a scratch image that receives only the compiled binary and the certificate bundle. The entrypoint is the binary itself. That is a small and honest container, and the reason to note it is the Go version, since 1.17 is well behind current releases and a module declaring that version will build with a current toolchain but is not being tested against one. The repository also carries a .pre-commit-config.yaml, a Dockerfile, a badges/ directory, a LICENSE file and a .github directory holding the daily update workflow that the preset procedure depends on.

## Conclusion

committers.top suits someone who wants a geographic view of open source activity, and it suits a contributor who wants to add a preset location, since the project documents a concrete procedure for that with a fork, a branch and a scheduled workflow. It is the wrong tool for an accurate global ranking, because the tool cannot sort by contributions directly and therefore has to sort by followers first, so a popular user with few contributions can outrank a prolific one, and it is the wrong tool if you need private contributions counted, since those are deliberately pushed to a subpage. Before running it, create a token with read:org and read:user permissions, and if you are adding a preset, follow the fork and daily update workflow steps rather than only editing presets.go. The last push was on 2026-10-22 and the repository publishes no releases.

## FAQ

### What does committers.top rank and how?

It queries the GitHub GraphQL API and ranks users by number of contributions for a set of preset locations. The API cannot sort by contributions directly, so the tool sorts by followers first to collect a larger candidate list and then sorts that list by contributions, which means a minimum follower count is required to appear on a list.

### What GitHub token permissions does committers.top need?

The README says the access token needs read:org and read:user permissions. It is created from the GitHub token settings page and passed to the tool with the --token flag.

### Why are private contributions not on the main country pages of committers.top?

The README states that private commits are included but are listed on a subpage rather than the main country page, and that this arrangement favours open source contributions over private ones. The public plus private count is available on a subpage of each region page.

### How do I add a new location preset to committers.top?

The README describes a multi-step process: update both your pull request branch and the gh-pages branch on your fork with upstream, trigger the daily update workflow on your fork using Run workflow with your pull request branch, verify the commit pushed to the gh-pages branch, and reference that commit in the pull request.

## Sources

- [ashkulz/committers.top on GitHub](https://github.com/ashkulz/committers.top)
- [Issues](https://github.com/ashkulz/committers.top/issues)
- [License: MIT](https://github.com/ashkulz/committers.top/blob/master/LICENSE)
- [Project website](https://committers.top)
- [README](https://github.com/ashkulz/committers.top/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ashkulz-committers-top