Spice up your code review process with gitStream

In my last blog post, I gave a short review of a GitHub tool called gitStream. Now it is time to deep diver and see what secrets it beholds and how it can improve our code review process.

gitStream is a free tool (for small teams) at GitHub developed by LinearB and it can be installed directly from GitHub market place. Tool can be installed for one repo, specific repos or for all repos in organization (their recommended option)

The app requires two files to operate, which should be located in GitHub repository:

• gitstream.cm file at .cm folder, that contains all the rules
• gitstream.yml file at .github/workflow folder, used by gitStream to execute automation in your repo

gitStream has templates for both files, so you don’t need to handcraft them to get started.

How it Works

When a new pull request or changes to an existing pull request is done the gitStream is triggered. gitStream searches for .cm file that contains rules with desired actions. For example we can label PRs by their complexity if the complexity is greater than what is defined in cm file.

gitStream uses special linear-b/gitstream-github-action to initialize the process. All PR updates (tagging etc.) are done through GitHub API.

See gitStream documentation for full process description.

Configuration

As mentioned earlier the configuration is done through .cm file. gitStream has an example configuration file in their web page, but lets tear it down line-by-line to see what it really does.

# -*- mode: yaml -*-

manifest:
  version: 1.0

automations:
  estimated_time_to_review:
    if:
      - true
    run:
      - action: add-label@v1
        args:
          label: "{{ calc.etr }} min review"
          color: {{ 'E94637' if (calc.etr >= 20) else ('FBBD10' if (calc.etr >= 5) else '36A853') }}

  safe_changes:
    if:
      - {{ is.formatting or is.docs or is.tests }}
    run: 
      - action: add-label@v1
        args:
          label: 'safe-changes'

calc:
  etr: {{ branch | estimatedReviewTime }}
is:
  formatting: {{ source.diff.files | isFormattingChange }}
  docs: {{ files | allDocs }}
  tests: {{ files | allTests }}

At line 6 we are starting new automation called “estimated_time_to_review”. The name can be what ever we like.
At line 8 and 9 we define that this automation is run always. We could add some other condition for example that if PR contains only code formatting, add tag “format-only”.
At line 10 to 11 we are calling action add-label, that adds time estimation of review. If the estimation is less than 20 minutes, we will put it in #E94637 color. If estimation 5-19 minutes we will use color #FBBD10 and otherwise #36A853. We could use any hex colors here.

At line 16 we are defining new action called safe_changes. It will be run only if code changes are formatting, docs or tests only. For those we will call add-label action that will add “safe-changes” label into PR.

Finally at lines 24 to 29 we are defining what those formatting, docs and tests only means. We are using built-in features like allDocs and allTests combined with files to iterate through all changed files. allDocs will try to figure out if changes contains only document changes (MD files etc.) and allTests scans for test files.

This is all nice, but where I think this tool really shines, is the review quality automation.

automations:
  the_right_reviewer:
    if: 
      - true
    run:
      - action: add-comment@v1
        args:
          comment: |
            {{ repo | explainRankByGitBlame(gt=25) }}
      - action: add-reviewers@v1
        args:
          reviewers: {{ repo | rankByGitBlame(gt=25) | random }}

If we have code files that are really hard to maintain and all the file changes should be carefully evaluated, we can use rankByGitBlame action to require PR review from those individuals who has worked with the code most. For example if we use gt=25 parameter it means, that only those who have contributed more than 25% of lines overall to that file are selected. By using random keyword we can select random person from that list. This is an easy way to find someone to review your code who has more comprehensive knowledge about the file and code.

Summary

gitStream is a powerful tool to improve code review process, but it requires lots of configuration to get it working properly. Every code base and team has a different characterics. Some team may have only one expert that is used in more complex reviews. Another team may have a pool of talented people, who should be used in code review only when absolutely necessary. With gitStream we can setup rules to help selecting correct people as reviewers, we can show additional information about the pull request, but all of these needs to be configured.