We, in Microsoft\u2019s Open Source team, occasionally write case studies to explain our work with a bit more technical depth for both external engineers as well as our fellow internal Microsoft engineers. Naturally, we don\u2019t want to embarrass ourselves. So before any case study is released, we have to get some peer reviews.<\/p>\n
Our blog is basically just a GitHub page, which means that every additional post is added to the site in the form of a pull request. Keeping track of which pull request is ready to be merged is quite tedious work, which is why we wrote a Node.js-driven bot that automates the whole flow<\/a>.<\/p>\n Managing the review workflow isn\u2019t fun. Depending on the size of your team, you probably have a bunch of pull requests in flight. If the engineering culture happens to be good, people are likely interested in collecting feedback early and often, meaning that your pull request list is a wild mix of various stages.<\/p>\n One would assume that self-management is a good solution – and it often is. Many teams just mark unfinished pull requests with a \u2018WIP\u2019 in the title or a \u2018wip\u2019 label, which is being updated by whomever opened the pull request. Without dwelling on the reasons, let\u2019s just say that our team is highly creative and very productive, but not exactly great at being a synchronized body, so the poor souls in charge of our website and case studies had to manually check and track the status of case studies, where they are in terms of reviews, and whether or not they\u2019re ready for release.<\/p>\n Instead of paying someone to constantly check all pull requests, we decided to use automation. GitHub comes with web hooks for all repositories – whenever a certain action is performed on a repository, GitHub can automatically post a JSON representation of the action to a given URL.<\/p>\n We registered a small Node.js bot that would respond to those events with a simple checklist:<\/p>\n Under the hood, the bot is just a small Express-driven app with one endpoint: http:\/\/botaddress.com\/pullrequests. A GET HTTP request will check the configured repo for open pull requests, while POST HTTP requests expects a GitHub-style JSON payload and handles only pull requests mentioned in it.<\/p>\n Using Mike de Boer\u2019s excellent GitHub Node module, we just had to describe all the individual interactions with GitHub<\/a> as well as a small router module describing the review flow mentioned above<\/a>.<\/p>\n If you too would like to require peer reviews of pull requests in your repo, you\u2019re in luck: Before we get started, let\u2019s do some required housekeeping:<\/p>\n The bot will need a GitHub user to interact with GitHub. You can just use your own account, but no good bot was ever written without a good robot pun. Head over to GitHub and create a new user, choosing from the many robots out there – Terminator, Tinman, Bender – choose wisely.<\/p>\n While the bot works fine with a username\/password combination, we recommend setting up an OAuth2 token. GitHub has API rate limits which are a little bit higher for OAuth-authenticated calls.<\/p>\n If you\u2019re using Azure, setting up a bot takes about a minute. Simply head over to the Peer Review Bot\u2019s repository<\/a> and click the \u2018Deploy to Azure\u2019 button. The Azure deployment wizard will automatically create a website for you; but also setup environment variables configuring the bot itself.<\/p>\n If you\u2019re anywhere else, make sure you\u2019re running Node (at least on 0.10.x). Then, setup configuration by either directly editing Maintaining a Workflow is Hard<\/h2>\n
Automation is Easy<\/h2>\n
\n
Let\u2019s Check Out Some Code<\/h4>\n
Setup Your Own Bot!<\/h2>\n
1) Creating a GitHub User for the Bot<\/h4>\n
2) Deploying the Bot<\/h4>\n
config.js<\/code> or by setting environment variables. Here are your options:<\/p>\n\n
user<\/code> User\/organization owning the repository<\/li>\nrepo<\/code> Repository to watch (case-studies)<\/li>\nbotUser<\/code> Bot\u2019s GitHub username<\/li>\nbotPassword<\/code> Bot\u2019s Github password<\/li>\nlabelReviewed<\/code> Name of the label indicating enough peer reviews<\/li>\nlabelNeedsreview<\/code> Name of the label indicating missing peer reviews<\/li>\nreviewsNeeded<\/code> Number of reviews needed<\/li>\ninstructionsComment<\/code> Comment posted by the bot when a new PR is opened – if you use {<\/span>reviewsNeeded<\/span>}<\/span><\/code> in your comment, it\u2019ll automatically be replaced with the number of reviews needed<\/li>\nmergeOnReview<\/code> (default: false) If set to true, the bot will automatically merge a PR as soon as it consideres it revieweed<\/li>\n