giscus: a comment system that lives in GitHub Discussions
A commenting system powered by GitHub Discussions. :octocat: :speech_balloon: :gem:
At a glance
- What is it?
- giscus turns a GitHub Discussion into the comment thread for any page, with no database and no tracking. Here is how the mapping works, how to install it, and when it is the wrong tool.
- Who is it for?
- giscus fits a site whose readers already have GitHub accounts and whose author is willing to moderate inside GitHub Discussions. It does not fit anonymous comment sections, audiences without GitHub logins, or teams that need moderation outside GitHub Discussions.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 173 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- giscus/giscus12,224 ★ · +106
| Repository | 2026-09-22 | 2026-11-15 |
|---|---|---|
| giscus/giscus | 12.1k | 12.2k |
106 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The problem giscus solves for static sites
A site generated by a static site generator has no server to store comments on. The usual answer is a hosted service that keeps the thread in its own database, which means the comments belong to that service and leave with it. giscus takes a different route: the thread is a GitHub Discussion in a repository you control, and the widget is a script that reads and writes to it through the GitHub API.
The README states the design goals plainly: no tracking, no ads, no database needed, and all data stored in GitHub Discussions. That last point is the real differentiator. If giscus shuts down tomorrow, the discussions remain in your repository, readable and exportable through GitHub's own interface. Moderation happens where you already review code and issues, not in a separate dashboard.
The audience is narrow and specific. It suits a technical blog, documentation site, or project page whose readers plausibly have GitHub accounts, because commenting requires authorizing the giscus app through GitHub's OAuth flow. A recipe blog read by people without GitHub logins will get reactions but very few comments.
How the page-to-discussion mapping works
When the script loads, giscus calls the GitHub Discussions search API to find the Discussion associated with the current page. The association is not stored anywhere in your site; it is computed from a mapping you choose at configuration time. The README lists URL, pathname, and title among the options.
If no matching discussion exists, nothing appears until someone acts. The README says the giscus bot creates the discussion automatically the first time a visitor leaves a comment or a reaction. That lazy creation is a deliberate trade-off: you do not have to pre-create hundreds of threads, but it also means a page's discussion does not exist until a human triggers it, so an empty page and a page whose discussion failed to match look identical to a visitor.
Commenting requires authorizing the giscus app to post on the visitor's behalf via GitHub OAuth. There is an escape hatch: a visitor can go to the GitHub Discussion directly and comment there, and the widget will pick it up. The README also notes that giscus automatically fetches new comments and edits from GitHub, so the widget is not a snapshot taken at page load and abandoned.
Installing giscus on a page
The README points at giscus.app as the configuration surface, and the repository's .env.example shows the environment variables the hosted app runs on, including NEXT_PUBLIC_GISCUS_APP_HOST, GITHUB_APP_ID, GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, and GITHUB_PRIVATE_KEY. Those are for running the service yourself, not for embedding the widget. For ordinary use you generate a script tag from the configuration page and paste it where the comments should appear.
The README does not print a full embed example, so the safest path is to use the tag the configuration page produces rather than hand-writing attributes. The repository does show how the client script itself is built, which is the closest thing to a code reference in the project files:
"scripts": {
"cscript": "tsc client.ts --outDir public",
"cthemes": "postcss styles/themes/*.css --dir public/themes --config styles/themes",
"dev": "yarn cscript --watch --preserveWatchOutput & yarn cthemes --watch & next dev",
"build": "yarn cscript && yarn cthemes && yarn mscript && next build"
}Those scripts compile client.ts into public and build the CSS themes before Next.js runs. They matter only if you are working on giscus itself or self-hosting it.
After the embed script runs, a comment box should render in place. If it does not, a likely cause is that the giscus app has not been installed on the target repository. Installing the app on the repository is a separate step from adding the script.
Self-hosting is covered by SELF-HOSTING.md and requires the GitHub App credentials plus the Supabase and Valkey variables listed in .env.example, including SUPABASE_KEY, SUPABASE_URL, and VALKEY_URL. If you only want comments on your site, none of that applies.
Where giscus is the wrong tool
The comment box requires a GitHub account. That is not a minor friction point; for a general-audience publication it removes most of the potential commenters. If your readers are not developers, a system that accepts an email address will produce a livelier thread than giscus will, even if the thread is worse organized.
The README carries its own warning: giscus is still under active development, GitHub is still actively developing Discussions and its API, and some features may break or change over time. That is an honest statement of a real dependency risk. Your comment system's uptime is coupled to the stability of a GitHub API you do not control, and a token or permission change on GitHub's side is not something you can patch locally.
Mapping collisions are the quiet failure. If two pages resolve to the same mapping value, they share one discussion and neither the widget nor the reader is told. Choosing pathname or URL reduces the chance, but any page whose URL changes after publication will look for a discussion that no longer matches, and the old thread stays orphaned in the repository.
Moderation happens on GitHub, where the README says you can moderate the comments.
giscus against utterances and Disqus
giscus is heavily inspired by utterances, and the README says so. The difference is the storage backend: utterances stores threads as GitHub Issues, while giscus stores them as GitHub Discussions. Discussions support threaded replies and reactions natively. Issues were never designed as a comment store.
Disqus works the opposite way. It is a hosted service with its own accounts, its own database, and its own moderation console, and it does not require a GitHub login. That makes it accessible to a non-technical audience and independent of GitHub's API, at the cost of the comments living on Disqus's infrastructure rather than in a repository you can clone. giscus's README states there is no tracking and no ads; that is a claim about giscus's own behaviour, and it is the axis on which the two systems differ most.
Migration is supported in one direction. The README explains that if you previously used a system built on GitHub Issues, such as utterances or gitalk, you can convert the existing issues into discussions, check that the mapping between discussion titles and pages is correct, and giscus will pick them up. The reverse, moving from GitHub Discussions into a hosted service, is not described.
Licence, maintenance, and upgrade cost
giscus is MIT licensed, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are retained. The repository also carries a PRIVACY-POLICY.md at the top level, which is relevant if you embed the widget on a site with its own privacy obligations. Nothing here is legal advice; read the MIT text and the privacy policy yourself before shipping.
The last push to the repository was on 2026-05-26, roughly five months before this writing. That is recent enough that the project is not dormant, but the README's own note about GitHub Discussions and its API still evolving means you should read CHANGELOG.md before pinning a version, not after. The repository has no published GitHub releases, so there is no tagged version to point at; upgrades mean tracking the main branch or the hosted deployment.
If you embed the hosted script, upgrades are invisible to you and arrive whenever the maintainers deploy. That is convenient and also means a change in widget behaviour can appear without any action on your part. If you self-host, you inherit the full build: TypeScript compilation of client.ts, a PostCSS theme build, a Closure Compiler pass, and a Next.js build, plus the GitHub App credentials, Supabase key and URL, and Valkey connection string that .env.example enumerates. That is a meaningful operational surface for a comment widget, and it is the price of not depending on someone else's deployment.
Editorial conclusion
giscus fits a site whose readers already have GitHub accounts and whose author is willing to moderate inside GitHub Discussions. It does not fit anonymous comment sections, audiences without GitHub logins, or teams that need moderation outside GitHub Discussions. Before wiring it in, verify three things: that the giscus app is installed on the repository you intend to use, that a discussion actually appears after the first test comment, and that your chosen mapping input (pathname, URL or title) is unique across every page you publish, because a collision silently merges two pages into one thread.
Frequently asked questions
How do I use giscus on my site?
Configure the widget on giscus.app, then paste the generated script tag where comments should render. The script finds or creates the Discussion for the page using the mapping you selected, and commenting requires authorizing the giscus app through GitHub OAuth.
What is giscus?
It is a comments system powered by GitHub Discussions, heavily inspired by utterances. There is no database: all comment data is stored in GitHub Discussions in a repository you choose.
What is the giscus app?
It is the GitHub App that posts comments on a visitor's behalf after they authorize it through GitHub's OAuth flow. The app must be installed on the repository before the widget can work there.
Why does giscus say it is not installed on this repository?
The widget needs the giscus GitHub App installed on the repository that you configured. Adding the script tag does not install the app; that is a separate step done through GitHub.
How does giscus compare with Disqus?
Disqus is a hosted service with its own accounts and database, so commenters do not need GitHub. giscus stores threads in GitHub Discussions and requires a GitHub login to comment, and its README lists no tracking and no ads.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/giscus-giscus)Star history chart for your README
[](https://hysenlabs.com/projects/giscus-giscus)Was this useful?