Documentation

Why Friendly Fire - a separate pull request assignment service?

What does Friendly Fire offer that is not available out-of-the box elsewhere? After all, GitHub already has round-robin code review assignment, and there are multiple bots for Slack and other services that will do the same.

The problem is, there is no straight-forward way to connect the same user on GitHub and Slack. They will most likely be notified via email, but the message risks going ignored - until the PR author has to "ping" the reviewer. This is especially true for active pull request comment threads.

PRs can be "stuck" in review unacceptably long, as we are uncomfortable bothering our busy team members. So what do we do? We need to take as much of the human factor as possible out of this equation. Linus Torvalds - the author of Linux - famously claimed in this TED Talk that he wrote Git in part to minimize human interaction. While there is no need to go to such extremes, let's admit it - there is often way too much process and overcommunication in the workplace, and the important stuff that keeps our work moving along can get easily lost in action.

Friendly Fire offers laser-focused notifications by letting you connect GitHub and Slack users, in addition to other unique features covered here.

What about CODEOWNERS?

The need to select better-matching code reviewers has been apparent for years now, and that's why GitHub in 2017 introduced CODEOWNERS. This system allows for matching reviewers to specific files and directories - which is also critical in a monorepo. After all, you do not want to assign your data scientists to front-end JavaScript files - that's just a waste of everyone's time.

CODEOWNERS, however, has limitations:

  • You need to commit a file every time there is a change on your team.
  • The above is even more painful with multiple repositories.
  • Any updates to file-matching patterns also results in a commit - and a pull request!
  • There is no integration with Slack users.
  • There are no other advanced features like reminders, PR ignore rules, or "away" status support.

In short, CODEOWNERS attempts to solve a big problem, but in our view - it doesn't go all the way, and can't really get there by design. What you get instead is a basket of options that you need to hunt down all over the place and glue together. This is exacerbated if you have a small team and a lot of repositories to worry about.

Friendly Fire puts it all in one place, easy to navigate, completely detached from your code.

Step 1: Add reviewers

Since Friendly Fire does not have access to your source code or commits, we cannot automatically figure out who should be reviewing the pull requests - this step needs to be performed manually.

Once you log in, you will be shown the "Repositories" screen, where you can go into a repository and add code reviewers. To make things easier, you will be presented with top 10 collaborators that can be added with one click. Any user from GitHub can later be added using the "Add Reviewers" button, but you will be given a warning if that particular user is not a collaborator. Non-collaborators will be not assigned to PRs as they do not have the required access level.

Add reviewers

Step 2: Connect the app and GitHub users to Slack

You must first associate your Slack workplace with Friendly Fire before any Slack notifications can go out by going into the Settings screen. The system will automatically attempt to match GitHub and Slack users as long as their full name in both systems matches. You can later connect the rest of the users either in the Reviewers or the All Users screens.

Connected to Slack

Important! After connecting the app to your Slack Workspace, you must invite the app into the group channel, if there is one. The group channel can be configured in the same Settings screen. Having Friendly Fire in the common group channel is not required but highly recommended - this allows for PR assignments, reminders, and heads-up messages to be visible by team members.

Configure reviewers

There are two important settings most reviewers in the system should have - association in Slack and file matching patterns.

On both the Reviewers and the All Users screens, each user is displayed with their GitHub and Slack handles. If the Slack handle instead says "Connect to Slack", click the button and a search dialog will pop up, allowing you to find the user in your Slack team list.

Connect to Slack

Per each repository, you have the option of configuring a set of file-matching patterns for each reviewer. If no patterns are defined, the catch-all "*" is assumed and the user will be assigned in round-robin fashion to all incoming pull requests.

File-matching expressions

Configure global review settings

Once you have reviewers added and Slack connected - you are pretty much ready to go - but you still may want to fine-tune the behavior of the system to fit your needs. These can be configured on the Settings screen:

  • The minimum number of reviewers to be assigned to each PR.
  • The Slack team channel where all group communication happens:
    Notifications
  • Behavior to follow when there are not enough reviewers selected:
    Fallback options
  • Up to two reminders for reviewers who do not take action on a code review:
    Reminders
  • Slack emojis that mark an unavailable user - they will not be assigned to PRs.
  • Ignore patterns based on PR title or owner username.

Troubleshooting the Slack connection

If you do not see Friendly Fire in the list of apps in the Slack left-hand bar: You should be able to see the "Open in Slack" button on our Slack app store page, if the correct workspace is selected. Click the button to "nudge" the app to appear in the App list.

Open app in Slack

If you are trying to invite Friendly Fire into a public channel, but you do not see the integration: Assuming you can see "Friendly Fire" in the left-hand bar (see the first tip), right-click the app → View App Details. From here you can invite the app into a team channel.

Slack app options