Using utteranc.es with a private repository

utteranc.es is a set of scripts that adds comment functionality to static site. It makes use of GitHub to handle authentication, editing, storage, etc. A GitHub issue is created for each post, and each comment on a post is stored as a comment on the corresponding issue. It even has support for reactions.

For many sites, setting up utterances will be a straightforward matter of adding an appropriate <script> tag to embed the comments widget and installing the utterances GitHub app on the relevant repository. This does mean your readers will need a GitHub account to post comments, but technical readers will probably already have one and it's pretty straightforward to create one anyway.

But what if you want to use utterances with a private repository? For example, the site might be an internal documentation site or an internal blog. utterances sadly does not support private repositories at the moment. There two main changes that need to be made:

1. The widget needs to be modified to require sign-in before displaying comments. At the moment, it will attempt to fetch comments from the repository's issues list and promptly fail if the repository is private and the user isn't signed in.
2. In src/utterances.ts, loadUser should be called before loadIssue so the user is logged in before the search request is sent.

A little bit of work also needs to be done to support posting comments to a private repo. Currently, comments are posted via the utterances GitHub bot, so you will need to add the bot as a collaborator to the repository, and someone on the utterances team will need to accept that invitation. This does mean that the utterances-bot will have full access to your private repository, which may less than ideal.

Self Hosting

My solution to the above was to self-host utterances. There are two key components of utterances:

1. the widget, i.e. the main utterances repository that contains the client.js script to be embedded on your site
2. the oauth handler, which handles the oauth callback from GitHub and passes the token to the widget

Anyone interested in self-hosting utterances can find my forked repositories here:

• hueyy/utterances - I've hosted this on GitHub pages
• hueyy/utterances-oauth - I'm running this as a Cloudflare Workers on Cloudflare's generous free tier

There were some gaps in the existing documentation which I have yet to properly fill in but have briefly outlined in the relevant READMEs, for my future self and anyone else who might embark on this.

You can find the final result below.