giscus: GitHub Discussions as a Comment System for Any Website

What giscus Does and Who Should Use It

giscus is a comment system for websites that uses GitHub Discussions as its storage backend. The README describes it as heavily inspired by utterances, an older system that stored comments in GitHub Issues rather than Discussions. The shift to Discussions matters because GitHub designed Issues for bug tracking and feature requests, while Discussions is structured for open-ended community conversation. giscus operates on Discussions because that backend aligns better with the comment use case.

The target audience is developers who run static websites, documentation sites, or technical blogs and want a comment section without hosting a database or subscribing to a third-party service. Because giscus stores all content in a GitHub Discussions thread, site owners moderate comments directly in the GitHub interface and do not need a separate admin panel or moderation tool.

The README states that giscus has no tracking, no ads, and is always free when using the hosted service at giscus.app. The service is open source and self-hostable for teams that want to control the hosting entirely. Visitors who want to comment must authorize the giscus GitHub App to post on their behalf through the GitHub OAuth flow. Anonymous comments are not possible. This is a deliberate design constraint, not a configuration option: anyone unwilling to require GitHub accounts from their visitors should evaluate a different comment system.

How giscus Maps Pages to GitHub Discussions

When giscus loads on a page, it calls the GitHub Discussions search API to find the Discussion thread associated with that page. The mapping between the page and a Discussion can be configured in several ways: by URL, by pathname, by the page's HTML title attribute, or by a custom identifier embedded in the page. If no matching Discussion exists, the giscus bot creates one automatically the first time someone leaves a comment or reaction.

This mapping mechanism has a practical consequence for sites that change their URL structure or page titles. If you move pages, rename URL slugs, or change title attributes after comments have been created, the existing Discussions become unlinked from the new page addresses unless you also update the Discussion titles in GitHub. The README mentions this configuration flexibility but does not describe a bulk migration path for URL changes; the ADVANCED-USAGE.md file in the repository covers mapping options in more detail.

Reactions work through the same Discussion thread as comments. Visitors can leave emoji reactions on a page through the giscus widget, and those reactions appear both in the widget and in the corresponding GitHub Discussion. The widget polls GitHub automatically for new comments and updates, so new comments added directly in GitHub Discussions also appear on the site without a page reload.

Setting Up giscus on a Static Site

To add giscus to a site, visit giscus.app. The configuration page provides a form for selecting the repository, choosing a Discussions category, setting the page-to-Discussion mapping, selecting a theme, and configuring language. After filling in these options, the page generates a script tag to paste into the site's HTML.

The repository must have Discussions enabled and the giscus GitHub App must be installed on it before the widget will work. When the error message giscus is not installed on this repository appears in the widget, it means the App has not been installed. The App is available at github.com/apps/giscus and must be installed on each repository used with giscus.

For React, Vue, and Svelte sites, the README links to the giscus component library (github.com/giscus/giscus-component), which wraps the script tag in a framework-specific component. Custom themes are supported through the data-theme configuration option, which accepts a URL to a custom CSS file. The ADVANCED-USAGE.md file in the repository documents which CSS variables are available for theming and how to restrict giscus to specific allowed origins.

Migrating from utterances or gitalk is described in the README. Both systems use GitHub Issues; converting those Issues to Discussions using GitHub's built-in conversion tool is the first step. After conversion, updating the giscus configuration to map to the correct Discussion titles completes the migration.

Self-Hosting giscus: What the Deployment Requires

The repository includes a SELF-HOSTING.md file describing how to deploy a private instance instead of using giscus.app. The application is a Next.js project (the package.json shows next@^12.3.4 as a dependency) that requires a GitHub App registration with its own credentials.

The .env.example file at the repository root shows the full set of environment variables a self-hosted deployment requires:

NEXT_PUBLIC_GISCUS_APP_HOST=https://giscus.app
GITHUB_APP_ID=123456
GITHUB_CLIENT_ID=Iv1.abcd1234wxyz5678
GITHUB_CLIENT_SECRET=abcd1234wxyz5678abcd1234wxyz5678abcd1234
ENCRYPTION_PASSWORD=s0m3r4nd0mstr1ng!w1thh1gh3ntr0pys0m3r4nd0mstr1ngw1thh1gh3ntr0py!
VALKEY_URL=valkeys://username:[email protected]:6379

The VALKEY_URL variable indicates that a Valkey (or Redis-compatible) cache is used for storing installation access tokens. The .env.example also includes SUPABASE_URL and SUPABASE_KEY, indicating a Supabase database is required for persistent storage. Self-hosting therefore involves a Node.js hosting environment, a GitHub App registration, a Valkey instance, and a Supabase project. The README does not estimate setup time or infrastructure cost for this configuration.

The build scripts in package.json show that the self-hosted deployment also compiles a TypeScript client script and custom themes as part of the build: the cscript and cthemes targets compile client.ts and CSS theme files before the Next.js build runs.

Limitations: What giscus Cannot Do

giscus requires every commenter to have a GitHub account and to authorize the GitHub App. For sites targeting an audience that is not on GitHub, this requirement will prevent most visitors from commenting. There is no configuration to allow anonymous or email-based commenting.

The giscus widget renders inside an iframe loaded from giscus.app or from your self-hosted domain. Deep CSS customization of the widget's internal layout is constrained by the iframe boundary. Theming through the documented CSS variables and the custom theme URL mechanism is available, but making the widget visually indistinguishable from surrounding site content is not always achievable.

giscus does not provide email notification for site visitors when someone replies to their comment. Visitors who want to follow a thread after commenting must watch the GitHub Discussion directly or check the site again. The widget also does not support comment threading in the traditional sense: all comments appear as replies to the same Discussion, with reactions on the Discussion as a whole.

The README note that giscus is still under active development implies that the behavior of some features may change. For a production site, pinning to the giscus.app hosted version means you receive updates automatically; self-hosted deployments must track upstream changes manually.

giscus vs Disqus: A Different Storage Model

Disqus is a hosted comment platform that stores comments on its own servers, supports anonymous comments, provides a moderation dashboard, and injects advertising unless you pay for a premium plan. No repository setup is required; you embed a script tag with a site ID.

giscus stores comments in GitHub Discussions under the site owner's control, requires a GitHub account for commenting, shows no advertising, and is free on the hosted service. The practical trade-off is commenter friction: Disqus allows immediate commenting for anyone; giscus gates commenting behind a GitHub OAuth authorization step.

For technical documentation and developer-focused blogs, where readers are likely to have GitHub accounts anyway, giscus removes the Disqus advertising model and the privacy implications of sending visitor data to a third-party analytics service. For general-audience sites, product landing pages, or any context where most visitors do not have GitHub accounts, the authorization requirement makes giscus impractical. The choice between them reduces to audience: if your readers are developers on GitHub, giscus is the lower-friction path for the site owner; if they are not, Disqus or a similar service removes the GitHub dependency.

Maintenance and MIT Licence

The last push to the repository was on 2026-05-26. The repository has no GitHub releases; changes are tracked through CHANGELOG.md. The project is MIT-licensed, which permits commercial use, modification, and distribution without restriction beyond attribution. The README references a PRIVACY-POLICY.md file for information about what the hosted giscus.app service collects from visitors.

The package.json shows several active dependencies including preact@^10.23.2 (used in place of React for lighter bundle weight), @valkey/valkey-glide@^2.4.0, and swr@^2.3.0 for data fetching. The React and react-dom entries in package.json point to npm:@preact/compat, confirming the Preact substitution. These implementation details matter primarily if you are contributing to the project or running a self-hosted instance that you maintain.

Editorial conclusion

giscus suits developer-focused sites whose visitors already have GitHub accounts and where the site owner wants comment storage in GitHub Discussions without a third-party service. It is the wrong choice for sites with a non-GitHub audience, for workflows that require anonymous comments, or for teams unwilling to manage a GitHub App installation. Before deploying, verify that Discussions are enabled on your chosen repository and that the giscus GitHub App is installed there; the error message giscus is not installed on this repository appears when that step is skipped.

Frequently asked questions

Official sources

1. giscus/giscus on GitHub
2. Issues
3. License: MIT
4. Project website
5. README