Discourse Code Review

(Sam Saffron) #1

What it is?

The Discourse Code Review plugin provides 2 way integration with GitHub code repositories. It allows your team to review commits to a repository leveraging Discourse features and plugins such as assign, whispers, notification, custom workflows and so on. Each commit to a repository becomes a topic. Replies to the topic are mirrored on GitHub. Integration is bi-directional meaning you can comment on Discourse and see it in GitHub or comment in GitHub and see it in Discourse.

It provides a very powerful workflow for teams who need to to review all commits to any number of repositories.

It allows you to ensure that multiple team members are aware of all changes applied to repositories. You can mark commits for follow-up, assign out review work and more.

Can I see it in Action?

Discourse maintains https://review.discourse.org/ this site is public and anyone can sign up using GitHub credentials. The site only surfaces a subset of features to non staff members. A more complete example may be:

On GitHub the same topic looks like this:


To install the plugin add: https://github.com/discourse/discourse-code-review.git to your app.yml.

GitHub repo: https://github.com/discourse/discourse-code-review

Review cateory: https://review.discourse.org/c/discourse-code-review


The plugin relies on GitHub webhooks to discover repositories and changes on repositories. For a minimal configuration you will need to set the following setting to a secret string.

code review github webhook secret

Once set on your GitHub repository setup a webhook with:

Payload URL: https://YOUR_DISCOURSE/code-review/webhook
Content Type: application/json
Secret: the value of code review github webhook secret

The plugin provides the following additional site settings:

code review api username : GitHub is very restrictive with the number of anonymous API requests it allows, this setting allows you to use a users account keys for /comments and /commit requests. This heavily reduces chances of hitting rate limits.

code review catch up commits : number of commits to “catch up” and create topics for when you encounter a new repo.

code review pending tag: Tag to apply to all unreviewed commits, pending by default

code review approved tag: Tag to apply to approved commits, approved by default

code_review_followup_tag: Tag to apply to follow-up commits follow-up by default

code review allow self approval: Are staff allowed to approve own commits?


This plugin is being actively developed, we started gathering some feedback at: site feedback - Discourse Reviews


Discourse Yearly Review Plugin
(Dan Fabulich) #2

Can you say another few words about the advantages (and disadvantages, if any) of doing Github code reviews in Discourse? Why not use Github’s UI? (Why pay for Github if you’re not planning to use its UI?)



Does this also support discussing over pull requests? I feel that would also help a lot for example when there’s a one-man-band doing the dev, but he’s also accepting PRs.


(Sam Saffron) #4

I have a 1000 word blog post in my mind about it, but I can do a quick bullet point for now.

  • We still use PRs using GitHub UI and love doing PRs for lots of changes. Nothing has changed here. GitHub is fantastic, we love GitHub. They have an excellent workflow for changes that have not yet landed. However…

  • GitHubs workflow for changes that have been committed directly to the repository is terrible.

  • Review fills a gap that simply can not be filled with GitHub today, we would like at least one team member to review every change made to our various Discourse owned git repos. If we are to use the GitHub provided UI nobody will ever be allowed to do anything but pull requests. This would slow us down enormously.

  • We need the ability to communicate privately without the whole world knowing with regards to certain changes. For example: We better get this awesome fix deployed to <insert giant company name> ASAP, @sam can you take care of it ?

  • We need the ability to approve changes made or request follow-up, this is not something the GitHub UI offers.

  • We need the ability to assign particular commits to a user. Say @sam makes a commit containing some mistakes It is nice that we can directly assign him that particular commit, mark it for followup and then keep track of it being followed up.

  • Discourse is pretty fantastic at this whole conversation thing, and the little features make a pretty big difference, I can see when people are typing. I never need to refresh pages for changes to pop up. Quoting is really nice, image uploads are nice, and so on.

  • Discourse is really good at read state, you get very strong guarantees that you read every single thing once, with GitHub I have no idea what commits I read and which I did not. We have an incredibly efficient to cope with firehose of information.

And the list goes on…

So review acts as a complement to GitHub, we use GitHub at the moment to cope with changes that have not yet landed. And we use review to properly handle changes that have already landed.

It is all early days but this has transformed the way I work and taught me so much. @TheBestPessimist PR support will probably happen one day, but for now the big focus is around complementing the weak parts of our existing GitHub workflow. PRs are working really well for us.


(Cosmin Popescu) #5

Hello !

Congrats for idea :smiley:

It is possible to integrate this plugin with Bitbucket or Gitlab ?
Or private repos ?

Thank you !

1 Like

(hosna) #6

What about gitlab? I would be very happy to see this work with gitlab :star_struck:


(Sam Saffron) #7

Totally happy with a PR that adds support for gitlab


(Joe Buhlig) #8

We’re playing around with this for the ProCourse team and liking the concept quite a bit. One question, do you have a machine user set up for the API username setting? That way you don’t get unwanted commits from personal projects added?


(Sam Saffron) #9

The api username is only used to pull info, It never pushes, pushing happens using individual user Github api keys, but yeah a machine user is fine

1 Like

(Joe Buhlig) #10

Oh! Got it! It’s the Webhook piece on GitHub that decides which events to send. Had it backwards in my head. Thanks, Sam.

1 Like

(Bank Live) #11

Code me not show


How to set it?


(Dave McClure) #12

Wow. This is pretty crazy stuff!

How does the mapping to different repositories work? Is it 1:1 category:repo? Or something else?


(Sam Saffron) #13

Did you configure the web hook on GitHub to push to your site per the OP?

@mcwumbly yeah we do 1:1 category -> repo. Also it keeps the categories sticky by id so after it initially creates it you can move the category around.


(Bank Live) #14

No How to set between Github and Discourse.


(Joe Buhlig) #15

One challenge of doing custom Discourse development in a team setting is how to continue improving the quality and stability of the code we write for our clients. We’ve tried a couple things that didn’t work out, but this plugin and a dedicated Discourse instance work beautifully!

We now have this integrated into our daily workflow for reviewing and approving each commit and PR we work with at ProCourse.

I should note that we also added to it. We write stories for each feature or bug fix we take on in a dedicated internal Discourse. As such, we wanted relevant commits to be pushed into the topics for those stories so that everything was in one place.

So we set up a topic webhook on the Review site that sends every new topic to the internal site. Then we built a plugin for the internal site that consumes that webhook and creates mini-posts like this:


All we have to do is leave the topic id from the internal site as part of the commit message.

The commit itself will be pulled into the Review site and the creation of that topic triggers the webhook. The webhook receiver on the internal site checks for the topic id as part of the message and creates the mini-post on that topic.

I should also note that the commit message is linked back to the topic on the Review site as opposed to the commit on GitHub. We want it easy to get into the review flow.

All that to say, well done! Love this thing! :tada: