Gitalk: GitHub Issues as a Comment System, and What That Costs You

The problem Gitalk solves for static sites

A statically generated blog has no database and no server process, so it has nowhere to put a comment. Gitalk's answer is to treat a GitHub repository as the datastore. Each page maps to an issue, each comment is an issue comment, and the widget is a Preact component that reads and writes through GitHub's API. The README describes the project as "a modern comment component based on GitHub Issue and Preact", and the package description in package.json says "A comment plugin base on GitHub issues".

The intended user is a developer running a personal or project blog who already keeps the source in Git and does not want to run a database for a comment box. The README lists authentication with a GitHub account, serverless storage, support for personal and organization repositories, and localization for eleven language keys: en, zh-CN, zh-TW, es-ES, fr, ru, de, pl, ko, fa, ja. That list is the honest scope of the project. It is not a general purpose comment platform, and it does not pretend to be one.

How a page becomes an issue

The mapping is done by the id option. Its default is location.href, and the README warns that its length must be less than 50 characters. If you leave the default in place on a site with long URLs, you can exceed that limit, which is why the README suggests extracting a path fragment with a regular expression, for example location.href.match('/(?<=posts/)(.*)(?=/)/')[1].

There is a second lookup path. The number option defaults to -1, and the README states that if number is not defined, the issue is located using id. So you can pin a page to a known issue number instead of relying on URL matching, which is useful when a URL changes but the discussion should follow the page.

On the write side, Gitalk needs an OAuth token. Because a browser cannot exchange an authorization code for a token without hitting GitHub's token endpoint, and that endpoint does not send CORS headers, the README documents a proxy option whose default is https://cors-anywhere.azm.workers.dev/https://github.com/login/oauth/access_token, with a link to the underlying GitHub issue explaining the CORS problem. This is the part of the architecture most likely to break without any change on your side: the default proxy is a third party, and if it is unavailable, sign-in fails.

Issue creation is gated by the admin array. The README states that Gitalk creates an issue for a page automatically when the logged-in user belongs to admin, and that setting createIssueManually to true disables that and leaves creation to a human. New comments default to being sorted with pagerDirection set to 'last', and perPage defaults to 10 with a documented maximum of 100.

Installing Gitalk and rendering a first comment box

The README gives two installation routes. The npm route installs the package and pulls in the stylesheet from the dist directory.

npm i --save gitalk

import 'gitalk/dist/gitalk.css'
import Gitalk from 'gitalk'

The CDN route skips a build step entirely. The README shows both jsdelivr and unpkg variants of gitalk.css and gitalk.min.js, pinned to major version 1.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.css">
<script src="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js"></script>

Before any of that renders, two things must exist outside your code. You need a public GitHub repository to hold the comments, and you need a GitHub Application registered at github.com/settings/applications/new. The README is explicit that you must specify the website domain URL in the Authorization callback URL field. Getting that wrong is the most common first-run failure, because the OAuth round trip will not return to your page.

With those in place, add a container element and construct the widget. The README's Method One example looks like this, with the placeholder strings replaced by your own values.

const gitalk = new Gitalk({
  clientID: 'GitHub Application Client ID',
  clientSecret: 'GitHub Application Client Secret',
  repo: 'GitHub repo',
  owner: 'GitHub repo owner',
  admin: ['GitHub repo owner and collaborators, only these guys can initialize github issues'],
  id: location.pathname,
  distractionFreeMode: false
})

gitalk.render('gitalk-container')

The render method accepts a string selector or an HTMLElement and is the only instance method the README documents. After it runs, a signed-out visitor should see the comment list and a sign-in prompt; a signed-in admin should also see the path that creates the issue for that page. If you are on React, the README's Method Two imports from gitalk/dist/gitalk-component and passes the same options object as a prop. Note that the README says TypeScript definitions ship for the options and the Gitalk class, but definitions for React component usage are not included.

The client secret in the page source problem

The required options include clientSecret, and the README's own example places it in front-end JavaScript. Any value in front-end JavaScript is readable by anyone who opens the page. Gitalk's design accepts this because the OAuth application is scoped to a comment repository and the token is used for issue reads and writes, but it is still a credential you are publishing. If your threat model does not tolerate that, Gitalk is the wrong tool regardless of how well it renders.

The proxy default compounds the concern. The README points the OAuth token exchange at a public CORS proxy. That proxy sees the request. Self-hosting the proxy is possible in principle since the option takes a URL, but the README does not document a proxy implementation, so you are on your own for that piece.

Two smaller constraints are worth knowing before you commit. The id length limit of 50 characters is a hard boundary, and the README does not describe what happens when it is exceeded. The perPage option caps at 100, so a page with thousands of comments is paginated rather than fully loaded, and the README does not discuss performance at that scale. Finally, the README does not document rollback or a way to migrate comments out of issues, so treat the GitHub repository as the permanent record.

Gitalk against Gitment, Vssue, Utterances and Giscus

The README's own Similar Projects list names gitment and vssue, and the surrounding ecosystem includes Utterances and Giscus, which appear in what people search for around this project. The distinction that matters is where the comments live.

Gitment is the closest relative: it also stores comments as GitHub issues, and Gitalk's README lists it first among similar projects. The practical difference for a new deployment is that Gitalk is the one with a maintained localization set and a documented React component entry point, while the README gives no comparable feature list for Gitment.

Vssue takes the same issue-as-comment idea and generalizes the host. The README does not describe Vssue's internals, so the honest statement is that both projects put comments in an issue tracker, and Vssue's documentation is where you would check whether it supports hosts other than GitHub.

Utterances and Giscus take a different route: they render from GitHub Discussions or issues through a GitHub App installed on the repository, rather than through an OAuth application whose client secret sits in your page. That removes the secret-in-source problem, and it also means the widget is delivered as an embedded script rather than as an npm package you import and bundle. If you want to style the component, control the render call, or use the React entry point, Gitalk's library shape is the reason to pick it. If you want to avoid publishing a client secret at all, that is the reason to pick something else.

Maintenance, licensing and what an upgrade costs

The repository is not archived, and the last push was on 2026-07-05. The published version in package.json is 1.7.2. There is a CHANGELOG.md at the top level and a bump script that runs standard-version -a, so releases are cut from the repository rather than published by hand.

The build is a three-pass webpack setup: webpack.config.js for the main bundle, webpack.config.comp.js for the component build, and webpack.config.min.js for the minified output, all driven by npm run build, which first clears dist with rimraf. Tests run through jest, with npm run coverage for the coverage report and npm run lint for eslint over src. The devDependencies pin an older toolchain, including webpack 3.1.0, babel-core 6.25.0 and react 15.6.1 for the test renderer. Upgrading that toolchain is not a small chore, and nothing in the README or package.json suggests a migration path.

For consumers the upgrade surface is smaller than it looks. The public API is the options object, one render method, and the React component import. The README does not document a breaking-change policy, so read CHANGELOG.md before moving between minor versions. The licence is MIT, stated in both the README and package.json. MIT permits commercial use and modification with the copyright notice retained; it offers no patent grant, which matters if your organization cares about that, and this is a description of the licence text rather than legal advice.

Editorial conclusion

Adopt Gitalk if your audience is developers who already hold GitHub accounts, you are willing to register a GitHub OAuth application, and you accept that comment moderation happens inside a repository's issue tracker. Do not adopt it if you need anonymous comments, if you cannot expose a client secret in page source, or if you want a hosted service that keeps working when GitHub's OAuth endpoints change. Before wiring it into a template, verify that your callback URL matches the domain you actually serve, that each page's id stays under 50 characters, and that the admin list contains only accounts with write access to the comment repository.

Frequently asked questions

Official sources

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