Discourse GitHub

[Discourse]

	Summary	Discourse GitHub Allows staff to assign badges to users based on GitHub contributions. Also allows users to create Github Linkbacks, Permalinks, and display live PR status on oneboxes.
	Install Guide	This plugin is bundled with Discourse core. There is no need to install the plugin separately.

As this is an official plugin maintained by the Discourse team, Support, Contribute > Bug, Contribute > UX, and Contribute > Feature requests can be made in the respective categories here on Meta, and tagged with the appropriate plugin tag. Click on a link below to get one started.

 Support  Bug  UX  Feature

Features

GitHub Badges

Assign badges to your users based on GitHub contributions.

How to use:

1. Enable github badges enabled in Settings → Plugins.
2. Generate a GitHub access token and paste it into the github linkback access token setting. See below for instructions.
3. Add one or more URLs of the GitHub repos to scan for contributions to the github badges repos site setting.

How badge counting works:

Badges count commits across all repositories, and when a user contributes to multiple repos, all their commits are added together into one total count.

Committer Badges:

Badge	Commits Required
Bronze	1 commit
Silver	25 commits
Gold	1000 commits

Badge Progression: As users accumulate more contributions across any of the tracked repositories, they automatically progress through badge tiers. For example, if a user commits to Repo A and then Repo B, both contributions count toward their total, allowing them to progress from Bronze to Silver to Gold.

---

GitHub Linkback

Create a link from a GitHub pull request or commit back to a Discourse post where it is mentioned.

How to use:

1. Enable github linkback enabled in Settings → Plugins.
2. Generate a GitHub access token and paste it into the github linkback access token setting. See below for instructions.
3. Finally, add the projects you wish to post to in the github linkback projects site setting in the formats:
   • username/repository for specific repositories
   • username/* for all repositories of a certain user

---

GitHub Permalink

Replace GitHub non-permalinks with permalinks.

How to use:

1. Enable github permalinks enabled in Settings → Plugins.

---

PR Live Status

Display live status indicators on GitHub pull request oneboxes in posts and chat messages. The status updates automatically via webhooks when PRs change on GitHub.

Status Types

Status	Color	Description
Draft	Gray	PR is marked as draft
Open	Gray	PR is open and awaiting review
Approved	Green	PR has been approved by reviewers
Changes Requested	Orange	Reviewers have requested changes
Merged	Purple	PR has been merged
Closed	Red	PR was closed without merging

How to use:

Step 1: Enable the Feature

Go to Admin > Settings > Plugins and set github pr status enabled to true.

Step 2: Configure GitHub Access Tokens

To fetch PR status (especially for private repositories), configure GitHub access tokens.

Setting: github onebox access tokens

Format:

organization_name|ghp_your_token_here
default|ghp_fallback_token_here

You can specify tokens per organization, plus a default token used as a fallback. Each line should contain org_name|token where the token is a GitHub Personal Access Token (classic) with repo scope.

Example:

discourse|ghp_xxxxxxxxxxxxxxxxxxxx
my-company|ghp_yyyyyyyyyyyyyyyyyyyy
default|ghp_zzzzzzzzzzzzzzzzzzzzzz

Step 3: Set Up GitHub Webhooks (for Real-Time Updates)

To get automatic status updates when PRs change, configure a webhook on GitHub.

Generate a Webhook Secret:

openssl rand -hex 32

Set the github webhook secret site setting to your generated secret.

Create the Webhook on GitHub:

You can create the webhook at the organization level (to cover all repos) or per-repository.

For an organization:

1. Go to your organization’s Settings
2. Navigate to Webhooks (under Code, planning, and automation)
3. Click Add webhook

For a repository:

1. Go to your repository’s Settings
2. Navigate to Webhooks
3. Click Add webhook

Webhook Configuration:

Field	Value
Payload URL	https://your-discourse-site.com/discourse-github/webhooks/github
Content type	application/json
Secret	Your generated webhook secret
SSL verification	Enable (recommended)
Events	Select “Let me select individual events”

Select these events:

• Pull requests
• Pull request reviews

Click Add webhook to save.

Step 4: Verify the Setup

1. Create a test post with a GitHub PR URL
2. Verify the onebox displays with a status icon
3. Change the PR status on GitHub (e.g., approve it, or close it)
4. Within a few seconds, refresh the Discourse page — the status should update

You can check the webhook delivery status in GitHub’s webhook settings to confirm events are being sent and received successfully.

Status Priority

When a PR has multiple states (e.g., approved but also has changes requested), the status is determined by this priority:

1. Merged (highest priority)
2. Closed
3. Draft
4. Changes Requested
5. Approved
6. Open (default)

Review Status Logic

The feature fetches review information from the GitHub API to determine approval status:

• Takes the latest review from each reviewer
• Ignores “commented” and “pending” review states
• Shows “changes requested” if any reviewer has requested changes
• Shows “approved” only if reviews exist and none request changes

Where It Works

• Forum posts — Any post containing a GitHub PR onebox
• Chat messages — PR oneboxes in chat also display live status

Note: Inline oneboxes (when a link appears inline in text rather than as a full preview) do not display status icons.

Migrating from GitHub Status Theme Component

This feature replaces the GitHub Status Indicators theme component. The two are not compatible and should not be used together.

If you’re currently using the theme component:

1. Disable and remove the github-status-theme theme component
2. Enable this built-in feature via the github pr status enabled setting

---

Configuration

GitHub Access Token

In order for the linkback feature to work and the badges to be granted to your users, you need to provide a GitHub access token. You can generate your token here: Sign in to GitHub · GitHub.

The linkback feature requires the public_repo scope, and granting badges requires no scope (leave everything unchecked if you only want badges). Since the public_repo scope grants write access to repositories, we recommend you create a throwaway GitHub account that has access to no repositories and use it just to generate a token.

Token Scopes by Feature

Feature	Required Scope
Badges	No scope required
Linkback	public_repo
PR Status (public repos)	No scope required
PR Status (private repos)	repo

---

Site Settings Reference

Setting	Default	Description
enable discourse github plugin	false	Master switch for the plugin
github badges enabled	false	Enable GitHub contribution badges
github badges repos	(empty)	Repository URLs to track for badges
github linkback enabled	false	Enable linkbacks from GitHub to Discourse
github linkback access token	(empty)	Access token for linkback feature
github linkback projects	(empty)	Projects to create linkbacks for
github permalinks enabled	false	Replace GitHub links with permalinks
github pr status enabled	false	Enable PR status icons on oneboxes
github webhook secret	(empty)	Secret for webhook signature verification
github onebox access tokens	(empty)	Access tokens for GitHub API (format: org|token)

---

Technical Details

PR Status API Usage

When a GitHub PR onebox is generated, Discourse makes up to two API calls:

1. PR Data: GET /repos/{owner}/{repo}/pulls/{number} — Fetches basic PR information including state, merged status, and draft status
2. Reviews: GET /repos/{owner}/{repo}/pulls/{number}/reviews — Fetches review data to determine approval status

These calls use your configured access token if available, allowing access to private repositories.

Webhook Security

Webhook requests are verified using HMAC-SHA256 signature validation. GitHub signs the webhook payload with your secret, and Discourse verifies this signature before processing. Invalid signatures are rejected with a 403 response.

Webhook Events That Trigger Updates

• PR state changes (opened, closed, reopened)
• PR merged
• Draft status changes (converted to draft, ready for review)
• Pull request reviews submitted
• Reviews edited or dismissed

Performance Considerations

• Rebaking is queued as a low-priority background job to avoid impacting site performance
• Only posts/messages with full GitHub PR oneboxes are rebaked (inline oneboxes are skipped)
• Chat message rebakes skip notifications to prevent duplicate alerts

---

CHANGELOG

2025-12-10

• FIX: Skip notifications when rebaking chat messages from GitHub webhooks

2025-12-09

• FIX: Skip rebaking posts with inline GitHub PR oneboxes
• FIX: Avoid intermediate state when rebaking posts with oneboxes
• FIX: Rebake chat messages when GitHub PR status changes
• UX: Use min-height to prevent layout shift when the status icon changes
• UX: Reduce GitHub PR status icon size on mobile

2025-12-08

• FEATURE: Add “changes requested” status to GitHub PR oneboxes

2025-12-04

• FEATURE: GitHub PR live status icon

2025-11-10

• FEATURE: Allow and denylist for linkbacks

2025-11-08

• FEATURE: Add category ignore list for GitHub linkbacks

2024-12-20

• DEV: Move discourse-github to core (no longer requires separate installation)

Last edited by @zogstrip 2025-12-10T13:26:48Z

Check document

Perform check on document:

[ImmaZoni (Justin)]

여러 개의 링크를 처리하는 과정은 어떻게 되나요? 동일한 커밋 코멘트에 계속 추가하나요, 아니면 매번 새로운 코멘트를 생성하나요?

[satonotdead]

커밋과 PR 배지를 단순화할 수 있지 않을까요? 선택의 역설(The paradox of choice)을 피하고자 하니까요

현재는 포크를 한 뒤 커밋 배지만 삭제했는데, 물론 커밋 배지를 삭제하면 커밋 배지를 통한 직접 커밋 기록은 사라지고, 포크는 코어와 항상 동일한 상태를 유지하는 것과 같지 않으니까요.

[xomiamoore (Mia)]

@Discourse

• username/repository - 특정 저장소에 대한 것
• username/* - 특정 사용자의 모든 저장소에 대한 것

GitHub 조직의 경우 와일드카드 *가 제게는 작동하지 않아서, 결국 모든 저장소를 개별적으로 입력해야 했습니다. 조직과 개인 사용자 간에 이 문제에 대해 겪은 다른 분이 계신가요?

[greyli]

링크백 댓글 언어를 어떻게 설정하나요?

[cultiv (Sebastiaan Janssen)]

감사합니다. 이 플러그인을 정말 좋아합니다! 배지 시스템에 대해 혼란스러웠는데, 다른 주제에서 설명을 찾아서 다행이었습니다: Github Badges are not working. Its hard to see if I do something wrong or if the plugin is not working - #4 by simon

하지만 그 답변에는

이 플러그인은 6개의 배지를 생성합니다:

라고 언급되어 있습니다.

저는 이 배지들을 하나도 볼 수 없는데, 무슨 일이 있었는지 모르겠습니다. 이 배지들의 생성을 (재)실행할 방법이 있을까요?

[cultiv (Sebastiaan Janssen)]

제 질문을 스스로 답하자면, 몇 시간 후 예약된 작업이 실행되었고 그때 배지가 생성되었습니다.

@cultiv

이 배지 생성을 (재)트리거할 방법이 있을까요?

수동으로 이 작업을 수행하려면 sidekiq 작업을 트리거하는 것 같습니다.

[tomtjes (Thomas Reintjes)]

기능 요청: 링크백에서 카테고리 및/또는 태그 제외

Announcements 카테고리가 있으며, RSS 플러그인이 이 카테고리에 새로운 GitHub 릴리스를 자동으로 가져옵니다. 릴리스 노트가 이슈를 참조할 때, 해당 링크가 Discourse에도 표시되고 링크백이 생성되지만, 이는 누구에게도 도움이 되지 않으며 GitHub에 불필요한 혼란만 야기합니다.

RSS 플러그인에 설정된 사용자의 특정 게시물, 즉 카테고리나 태그, 또는 단순히 특정 게시물에 대해 링크백 생성을 제외할 수 있도록 해 주셨으면 합니다.

[david (David Taylor)]

이 플러그인은 이제 Bundling more popular plugins with Discourse core 에 포함된 Discourse 코어에 함께 번들링됩니다. 셀프 호스팅 중이시면서 이 플러그인을 사용 중이라면, 다음 업그레이드 전에 app.yml에서 플러그인을 제거해야 합니다.