Starring a repository adds it to a list on your account and increments a public counter.
That is the entire mechanism. Everything else about stars — what they imply, what they are worth, whether a project with 40,000 of them is better than one with 400 — is interpretation, and the interpretation is where almost all the mistakes happen.
This lesson covers the mechanism briefly and then spends most of its length on reading the number honestly, because deciding which dependencies to trust is a genuine engineering problem and stars are the metric people reach for first.
Stars, watching and forking
Section titled “Stars, watching and forking”Three actions that get confused constantly, because all three are buttons in the same corner of the page and all three imply some kind of interest.
| What it does | Notifications | Public | |
|---|---|---|---|
| Star | Bookmarks the repository, increments a counter | None | Yes — who starred is public |
| Watch | Subscribes you to repository activity | Yes, configurable | Yes |
| Fork | Creates a copy you own, linked to the original | None | Yes |
The one that catches people is watch. Starring a hundred interesting projects costs nothing. Watching a hundred projects fills your inbox with every Issue, comment and release from all of them, and the usual response is to stop reading GitHub notifications entirely — which means missing the ones that concern your own repositories.
If your notifications feel useless, the first thing to check is how many repositories you are watching, not your notification settings.
What starring is actually useful for
Section titled “What starring is actually useful for”Two things, and they are both about you rather than about the project.
Bookmarking. The starred list is a personal index of things you found and might want again. This is its most honest use, and it works better if you treat it as a bookmark list rather than an endorsement — star freely, and organise later.
Signalling appreciation. Maintainers do see the number, and for unpaid work on a project used by strangers, a visible count of people who found it useful is a real if modest form of feedback. It costs you one click.
You can organise starred repositories into lists, which turns an unusable pile of four hundred stars into something you can actually search. If you star more than a handful of things, this is worth doing.
Reading star counts honestly
Section titled “Reading star counts honestly”Here is the part that matters for engineering decisions.
A star count is a measure of how many people saw the repository and clicked a button. It therefore measures attention, filtered through visibility, accumulated over time. It correlates with quality only to the extent that quality drives attention — which it does, weakly, alongside many stronger factors.
Specific reasons the number misleads:
Stars accumulate and rarely decrease. People un-star far less often than they star. A project abandoned three years ago keeps the stars it earned when it was maintained. The count reflects historical peak interest, not current health.
Visibility dominates. A repository that reached the front page of an aggregator, was mentioned in a popular newsletter, or was posted by someone with a large following will out-star a better project that nobody saw. This is a difference in marketing, not in software.
Stars measure the pitch, not the product. Many stars come from people who read the README and never ran the code. A compelling README is a genuine skill, but it is not the same skill as writing maintainable software.
Categories are not comparable. A JavaScript framework and a niche protocol implementation have audiences differing by orders of magnitude. Comparing star counts across ecosystems tells you about audience size and nothing about the projects.
The number can be manipulated. Stars can be bought, and campaigns to inflate them exist. This is against GitHub’s terms and is acted on, but a count is not an audited figure.
What to look at instead
Section titled “What to look at instead”When you are actually deciding whether to depend on something, these signals answer the question stars only appear to answer:
| Question | Where to look |
|---|---|
| Is it maintained? | Date of the most recent commit and release, not the star count |
| Is it responsive? | Ratio of open to closed Issues, and how old the open ones are |
| Is it a bus-factor risk? | Number of contributors with meaningful commit counts |
| Is it tested? | CI configuration, and whether checks pass on recent commits |
| Is it releasable? | A tagged release history with notes, not just commits |
| Is it licensed for your use? | The licence file, read rather than assumed |
| Is it secure? | Advisory history, dependency freshness, whether it has a security policy |
| Will upgrades hurt? | Changelog quality and whether it follows semantic versioning |
Most of these are visible in under a minute, and every one is a better predictor than the star count.
A quick check from the terminal covers several at once:
gh repo view owner/project \ --json stargazerCount,pushedAt,isArchived,licenseInfo,openIssues \ --jq '{stars: .stargazerCount, lastPush: .pushedAt, archived: .isArchived, license: .licenseInfo.key, openIssues: .openIssues.totalCount}'What it doesPrints the repository's star count alongside signals that actually indicate health: last push, open Issues, archived status and licence.
Why we run itPutting stars next to the other fields makes the point directly — the star count is one number among several, and usually the least informative.
Expected resultA small JSON object with the requested fields.
Output:
{ "archived": false, "lastPush": "2026-08-19T14:22:07Z", "license": "apache-2.0", "openIssues": 143, "stars": 21847}Read that together rather than one field at a time. Twenty-one thousand stars and a push last week is a healthy picture. Twenty-one thousand stars and a last push in 2022 is a warning, and the star count is what makes it look safe.
Stars through the API
Section titled “Stars through the API”Stars are exposed programmatically, which is occasionally useful for inventory or reporting.
List what a user has starred:
gh api user/starred --paginate --jq '.[].full_name'Get the count for a repository:
gh api repos/OWNER/REPO --jq '.stargazers_count'Starring and un-starring are ordinary authenticated API calls:
gh api --method PUT user/starred/OWNER/REPOgh api --method DELETE user/starred/OWNER/REPORetrieving when each star was added requires a specific media type on the REST endpoint, which is a rare survival of the older Accept-header-driven API style:
gh api repos/OWNER/REPO/stargazers \ -H "Accept: application/vnd.github.star+json" \ --paginate --jq '.[] | {user: .user.login, at: .starred_at}'The timeline is more informative than the total. A repository that gained most of its stars in one week two years ago tells a very different story from one gaining them steadily — and only the timeline distinguishes them.
The ethics of the number
Section titled “The ethics of the number”Two things are worth saying plainly.
For maintainers. It is entirely reasonable to be pleased when the number goes up, and entirely unreasonable to treat it as a measure of your work. Excellent, heavily-used software sits at three hundred stars because it is infrastructure that nobody blogs about. Wanting the number to grow is normal; optimising for it means optimising for attention, which is a different project.
For everyone else. Using stars to dismiss a project is worse than using them to select one. “Only 200 stars” says nothing except that few people have seen it. Some of the best-engineered code on GitHub has a three-figure star count, because it does one thing properly for a small audience.
The honest position is that stars are a weak signal that is freely available, which is exactly why they are over-used. Weak and available beats strong and effortful, unless you make a point of doing otherwise.
Stars as a maintainer’s signal
Section titled “Stars as a maintainer’s signal”Star growth is one of the few pieces of feedback an unpaid maintainer gets, and it is worth understanding what it does to behaviour.
Projects that grow quickly attract a particular kind of pressure. Issue volume rises faster than contributor count, because reading is easier than fixing. Feature requests arrive from people with no stake in maintaining the result. The gap between “number of people depending on this” and “number of people helping” widens, and burnout in open source is very often that gap becoming unmanageable rather than any single bad interaction.
This has a practical implication for how you use somebody else’s project. A repository with a high star count and one maintainer is a risk, not a reassurance — the popularity is precisely what makes the bus factor dangerous. Checking contributor distribution is quick:
gh api repos/OWNER/REPO/contributors --paginate --jq '.[] | "\(.contributions)\t\(.login)"' | head -10Output:
1847 original-author94 frequent-contributor31 another-contributor12 occasionalThat shape — one person with an order of magnitude more commits than anyone else — is extremely common and tells you more about project risk than any number of stars. It is not a reason to avoid the dependency; it is a reason to know what you are taking on, and possibly to contribute.
A note on trending and discovery
Section titled “A note on trending and discovery”GitHub surfaces repositories through trending pages and recommendations, and star velocity is an input to those. This produces a feedback loop: a project that gains stars quickly becomes more visible, which causes it to gain stars more quickly.
Understanding the loop explains a pattern you will see repeatedly — a project appearing to come from nowhere to tens of thousands of stars in a fortnight, then flattening. That curve is a visibility event, not a sudden improvement in the software. The code was the same the week before.
It also explains why star counts cluster so strongly by recency. Projects launched during a period of high interest in their category carry counts that a technically superior project launched two years earlier will never reach.
None of this makes stars useless. It makes them a measurement of a social process, which is worth knowing about in its own right — just not a measurement of the code.
Common mistakes
Section titled “Common mistakes”Treating stars as a quality ranking. They measure attention, not correctness or maintenance.
Comparing across ecosystems. Audience sizes differ by orders of magnitude.
Watching instead of starring. Bookmarking a project should not subscribe you to its Issue traffic.
Ignoring the date. A high count with no recent activity is a project living on reputation.
Starring hundreds of things with no organisation. Use lists, or the bookmark value disappears.
Automating stars. Against the terms of service, and transparently so.
Lists and organising
Section titled “Lists and organising”Starred repositories can be grouped into lists, which is the difference between a usable bookmark collection and four hundred entries you never revisit.
A workable scheme uses lists for why you starred it rather than what it is:
| List | For |
|---|---|
| Using in production | Dependencies you actually ship |
| Evaluating | Candidates for a current decision |
| Learning from | Codebases worth reading |
| Tools | Things you install rather than import |
Categorising by language or domain rarely helps, because search already does that. Categorising by relationship does, because that is the thing you cannot search for.
Lists are not exposed through the public API in the way stars themselves are, so this is browser-based curation. Ten minutes once is usually enough to make an existing pile useful.
Exercise
Section titled “Exercise”- Pick three repositories you depend on in real work.
- For each, record the star count, the date of the last push, the number of open Issues and the
licence — using the
gh repo view --jsoncommand above. - Rank them by stars, then rank them by how confident you are depending on them.
- Compare the two orderings.
- Check how many repositories you are currently watching, and adjust anything you meant to star instead.
For most people the two rankings in step 4 do not match, and noticing the gap is the entire point of the exercise.
A closing note on metrics generally
Section titled “A closing note on metrics generally”Stars are a specific case of a general problem: a number that is easy to obtain standing in for a quality that is hard to measure.
The same pattern appears with commit counts as a measure of contribution, lines of code as a measure of effort, and pull requests merged as a measure of productivity. In every case the metric measures something real and adjacent, and in every case optimising for it degrades the thing it was standing in for.
The defence is the same each time: know what the number actually counts, prefer several weak signals over one, and be suspicious of any metric that is both easy to collect and easy to influence.
What you learned
Section titled “What you learned”- Starring bookmarks a repository and increments a public counter; it sends no notifications.
- Watching is the notification subscription, and over-watching is why notifications become useless.
- Stars accumulate, rarely decline, and are dominated by visibility rather than quality.
- Maintenance signals — last push, Issue responsiveness, contributor count, release history — answer the question stars only appear to answer.
- Stars are readable and writable through the API, and
starred_attimestamps are more informative than the total. - Automating stars violates GitHub’s terms of service.