GitComment

A comment section for your GitHub profile. Visitors leave you a message using the GitHub account they already have, and it shows up in your profile README.

Comments live in a GitHub Discussion on your profile repository. When someone posts, an Action redraws the board and commits it. No server, no database, no signup, no account to create.

Themes

Six of the ten, at a glance.

notes — the one above. Paper notes, tape, handwriting.

dev

comic

pink

win95

This one draws no background at all, so it sits directly on the page and follows whichever GitHub theme you are using.

retro

A guestbook page from about 2003, down to the visitor counter, which shows the real number of comments in your Discussion. Always renders as a light page; the dark variant just darkens the outer frame so it sits better on a dark README.

There are four more: drawn, cozy, steam and minimal. Those are plain README HTML rather than images, so every username in them stays clickable.

Changing theme

Edit .github/gitcomment.yml in your profile repository:

theme: dev
variant: dark

Commit it, then run the workflow once from the Actions tab. That's the whole process.

You can skip the config file entirely and set the theme in the workflow instead:

      - uses: LISK819129/GitComment@v1
        with:
          discussion-number: 1
          theme: dev
          variant: transparent

Those inputs win over the config file, so one file is enough to get started. The config file is for the settings that have no input: title, subtitle, blocked_users and moderation.

theme — notes dev pink comic win95 retro drawn cozy steam minimal

variant — dark light transparent

transparent draws no background and follows whichever GitHub theme the visitor is using. The four HTML themes ignore variant.

All values are lowercase. A wrong one fails the run with a message naming the valid options, and leaves your README untouched.

What it does

• Shows the newest few comments; the rest stay in the Discussion
• Real avatars and profile links
• Ten themes, three variants
• Hide or delete a comment and it disappears on the next run
• Blocklist, and an approval mode where nothing appears until you react to it
• Escapes everything a commenter writes, so nobody can inject markup

Setup

1. Enable Discussions on your profile repository — Settings, Features.

2. Create one Discussion for the comments. Note its number from the URL.

3. Add these two lines to your README where you want the board:

<!-- GITCOMMENT:START -->
<!-- GITCOMMENT:END -->

4. Add .github/workflows/comments.yml:

name: comments

on:
  discussion_comment:
    types: [created, edited, deleted]
  workflow_dispatch:

concurrency:
  group: comments
  cancel-in-progress: false

jobs:
  update:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      discussions: read
    steps:
      - uses: LISK819129/GitComment@v1
        with:
          discussion-number: 1

It has to be on your default branch — GitHub only fires discussion_comment for workflows that live there.

5. Actions tab, run it once by hand. Done.

No actions/checkout step. The Action reads and writes over the API, which also means two people commenting at the same moment can't clobber each other.

Config

All optional, at .github/gitcomment.yml:

title: "Comments"
subtitle: "little messages from people passing by."

theme: notes
variant: dark

max_comments: 6
message_max_length: 240

show_avatar: true
show_date: true

moderation: automatic
blocked_users: []

filter_profanity: false
blocked_words: []

max_comments is how many are drawn, not how many are kept. It defaults to 5 and can be anything from 1 to 25. Only that many of the newest comments appear on the board; everything older stays in the Discussion behind the older messages link, and nothing is ever deleted.

A README cannot scroll, so keeping this number small is the point. Past about 10 the board gets tall enough to push the rest of your profile off the screen.

Moderation

automatic shows everything as it arrives. Hide a comment with GitHub's own Hide menu and it disappears on the next run, or add the author to blocked_users.

approved shows nothing until you add a 👍 to the comment yourself. Reactions, because they work from the GitHub mobile app.

Turning approval on hides the comments already on your board, because none of them have been approved yet. If you would rather keep them, set a cutoff:

moderation: approved
approved_since: 2026-09-22

Anything posted before that date stays visible. Anything after it needs your reaction. Put today's date there on the day you switch approval on.

Filtering words

blocked_words drops any comment containing a word you list.

blocked_words:
  - crypto
  - airdrop

filter_profanity: true adds a built-in list of common profanity and slurs. It matches whole words only, so Scunthorpe, assets and cocktail are safe, and it sees through simple padding like fuuuck and sh1t.

It is a word list, not a moderator. It will miss things, and it only knows English. Treat it as a first pass and keep an eye on the Discussion.

Limits worth knowing

• The drawn themes are images, so nothing inside them is clickable — just a leave a message link underneath. Use drawn, cozy, steam or minimal if you want every username to be a link to their profile.
• Avatars are copied into the image, because GitHub's image proxy blocks outside requests. If someone changes their picture, yours updates on the next comment.
• Dates are drawn when the board is rendered, which is why they're absolute rather than "2h ago". A picture can't tell the time.
• A README can't scroll, so GitComment doesn't fake it. Newest few, then a link to the rest.

Development

npm install
npm test
npm run build

npm run try -- <owner>/<repo> <discussion> renders every theme against a real Discussion without writing anything, then npm run serve to look at them.

dist/index.js is committed because GitHub Actions runs it directly.

Credits

Handwriting is Caveat, SIL Open Font License.

License

MIT