Gitalk 2.0 moves comments to GitHub Discussions and makes you run your own token endpoint

A static page cannot finish GitHub's OAuth exchange, so Gitalk needs a server piece

Gitalk advertises no backend and no database, but there is one server-side component you cannot skip. GitHub's token URL, github.com/login/oauth/access_token, does not send an Access-Control-Allow-Origin header, and the device flow is blocked by CORS as well. A page running in a visitor's browser therefore cannot complete the OAuth exchange on its own. Something on a server has to hold the client secret and trade the OAuth code for a token.

In 1.x the answer was to put clientSecret in the page and route requests through a third-party CORS proxy, which exposed the secret to anyone who viewed source. Version 2.0 switches to a GitHub App and an edge function you own. The endpoint only ever sees an OAuth code or an encrypted session. It never receives the client secret from the browser, and a visitor's raw token never appears in a URL. Sessions last 30 days and renew silently when the App is configured to expire access tokens.

The built-in default proxy rejects every domain except the project's own

The proxy option defaults to the endpoint the Gitalk project runs. That default is not a shared public service. Its origin allowlist only covers the project's own sites, so a request from your domain is rejected by CORS before GitHub is ever contacted. The option table marks proxy as required in practice for this reason.

The deploy CLI handles this in one command on Cloudflare's free tier, in about a minute:

npx github:gitalk/deploy -c .env -t cloudflare

CloudBase is the second target, selected with -t cloudbase, and it needs a CloudBase environment plus Tencent Cloud keys. Self-hosting on Node is also supported. After deployment you pass the printed origin to the widget:

{ proxy: 'https://my-niubi-gitalk.octocat.workers.dev' }

The repository preparation, App permissions, credentials, .env contents and callback URL are covered only in packages/gitalk-deploy/README.md; the top-level README deliberately does not repeat them, so you have to read that second file to finish setup.

Creating the GitHub App does nothing until it is installed on the comment repository

Setup step one is the only step that needs a browser and a repository you administer: create a GitHub App and install it on a public repository with Discussions enabled. The installation is the part people miss. The token endpoint mints an installation token from that installation, so without it the proxy has no token to use.

The consequence shows up in rate limits rather than as an error. With proxy set and the App installed, logged-out visitors read through your proxy's canonical GraphQL path and draw on the installation token's budget of 5,000 requests per hour. With no proxy, or with the App created but not installed, logged-out reads go to GitHub REST straight from the browser and are capped at 60 requests per hour per IP. A page can look fine in testing and then stop loading comments for visitors behind a shared address. Logged-in visitors use their own token, at 5,000 per hour.

Anonymous reads fall back silently when the proxy path fails

When proxy is configured, Gitalk tries the GraphQL path through your endpoint first. If that path cannot answer, because the proxy is unreachable, the App is not installed, or the repository is private, the widget falls back to a CORS-enabled REST read made directly from the browser. That read needs no credential, but it spends the anonymous per-IP budget of 60 requests per hour.

The fallback keeps comments visible, which is good for readers, but it also hides misconfiguration from you. A broken proxy deployment does not throw a visible failure; it quietly moves every anonymous visitor onto the low limit. A private repository also forces this path, which means the comment store needs to be public for the high-limit read path to work. The measured behaviour for each combination is recorded in docs/tech.md section 2.1 in the repository.

Posting always requires a GitHub sign-in because Discussions writes are GraphQL only

GitHub exposes no REST write API for Discussions. Every write has to go through GraphQL with a token, and that is why Gitalk requires a visitor to sign in with GitHub before posting. There is no anonymous comment mode and no guest name field.

For a site owner this narrows the audience to people with GitHub accounts. That is a reasonable fit for a developer blog or project documentation and a poor fit for a general audience. It also means every comment is tied to a real GitHub identity and stored in a repository you own, in plain view on GitHub.

Thread creation is restricted separately. The admin option, which defaults to an empty array, lists the users allowed to create the discussion on first visit. If nobody on that list has visited a page yet and no existing discussion matches, there is no thread for others to comment in.

Passing number avoids a title scan when matching pages to discussions

Each page needs to map to one discussion. The number option names the discussion directly, and it is marked as recommended because it avoids a title scan. Without it, Gitalk falls back to the id option, which defaults to location.pathname, as the page identifier. If your URL structure changes, a pathname-based id no longer matches the old thread, while a fixed number keeps working.

The rest of the options are short. clientID is the GitHub App's client ID, not the old OAuth App ID. owner and repo name the repository holding the discussions, and repo takes the name only, never the owner/repo form. backend defaults to 'discussions'. category is the Discussions category slug or name used when creating a thread. perPage defaults to 10. language defaults to navigator.language, with 11 locales carried over from 1.x. The widget ships as framework-free ESM and IIFE builds plus React and Vue wrappers.

Old 1.x comments stay in Issues, and the clientID changes anyway

Gitalk 1.x stored comments in GitHub Issues. Version 2.0 stores them in Discussions, and existing comments do not move. If you upgrade without changing anything, your old threads will not appear. To keep reading and writing them, set the backend explicitly:

{ backend: 'issues' }

Even with that option, migration is not a drop-in swap. 1.x authenticated through an OAuth App and 2.0 needs a GitHub App, so the clientID value changes, and you still need the token endpoint. The 1.x line itself is finished: v1.8.1, released on 2026-10-16, is labelled the final 1.x release and end of life. The toolchain moved too, from webpack 3, Babel 6 and Preact 8 with UMD-only output to Vite 8, TypeScript 7 and Preact 11, and versioning moved from standard-version to release-please.

Version 2.0 is still a beta, and the npm packages may not exist yet

The newest release is v2.0.0-beta.2, published on 2026-10-18 and described as a preview of the rewrite. The last push to the repository was on 2026-10-19. The install path for 2.0 is a set of scoped packages:

pnpm add @aifire/gitalk          # framework-free
pnpm add @aifire/gitalk-react    # React
pnpm add @aifire/gitalk-vue      # Vue

There is also a no-build option that loads gitalk.css and gitalk.js from jsDelivr under @aifire/gitalk@latest. The README carries a warning, though: until the first release is published, these packages are not on the registry, and you have to build from source instead. Check npm before writing an install step into your site's build, and be aware that the @latest CDN URL will track whatever gets published next. The code is MIT licensed.

Editorial conclusion

Gitalk 2.0 suits site owners who want comments stored in a GitHub repository they control and who are willing to create a GitHub App, install it on a public repository, and deploy a token endpoint on Cloudflare, CloudBase or Node. It does not suit anyone who wants a pure drop-in script with no server piece, or anyone who needs a stable release today: 2.0 is at v2.0.0-beta.2 and 1.x has reached end of life at v1.8.1. Before switching, confirm the @aifire packages are published on the registry, and plan for 1.x comments staying in Issues.

Frequently asked questions

Official sources

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