Improve GitHub Collaboration

Turn those stormy developer seas into smooth sailing

Photo by Scott Osborn on Unsplash

I’m currently working with development teams in the Czech Republic, Poland, New York, and San Fransisco. On top of that, every team is now working remotely. With async communication now the norm, I’m constantly working to make that processes more efficient. Efficiency in communication helps maintain velocity by reducing churn. One area where this can be a real challenge is GitHub. If your code pipeline is starting to look like a train wreck, consider implementing the tools below. They can save you from backing out commits, needless pull request revisions, and clogging your CI/CD pipelines with predictable build failures.

Create a Code Owners File

A code owners file is a great way to ensure those developers who are responsible for the integrity of your code always review changes by automatically adding them to pull requests. The syntax allows you to attach specific paths to an explicit lists of developers who are responsible for maintaining them.

/.github/* @doriansmiley @borismedovnik

/src/* @doriansmiley

/scripts/* @borismedovnik

/start_app.sh @borismedovnik

In this example I would be included on any changes under src, Boris would be included on any changes to scripts and start_app.sh, and we both would be included on changes to files under .github. Developers can always request additional reviews, but these are added automatically. Check out the syntax guide for more details.

Enable Required Review of Pull Requests

Once you have a code owners file on place you should enable mandatory reviews. Required reviews allow you to protect branches (such as master) from a direct commit, define the number of reviews, and require review from code owners based on the rules defined in your code owners file. For complete instruction see the official guide.

Use a Pull Request Template

Now that you have code owners and required pull request review enabled, it’s a good idea to make sure developers open pull request that are properly formatted with all the required information to perform the review. To do this setup a pull request template. This is one of the best ways to save time and reduce churn. Bad pull requests that don’t contain good, actionable information are just as bad as bug reports that don’t contains steps to reproduce, expected and actual outcomes. Below is an example:

# What is the purpose of this change?
<!--
What functionality does this introduce, or what feature does this fix? How and why?
Please link to issue in Jira
-->


<!-- You can erase any parts of this template not applicable to your Pull Request. -->

* [ ] Have you checked that it works
* [ ] Have you written unit tests, as applicable?
* [ ] Have you added typings, as applicable?

A PR template is just a markdown document that contains all the required info a team would need to evaluate the change. You may even be able to use GitHub’s webhook feature to automatically close PRs that don’t contain the information defined in your template!

Use Singed Commits with GPG

If you work on sensitive repos and want to ensure every commit comes from a trusted source setup signed commits. I would setup signed commits for anything effecting my infrastructure such as terraform scripts. Follow the steps in the GitHub guide to enable signatures. Once complete developers can sign commits with $ git commit -S -m your commit message. It’s kind of a pain to sign commits after the fact, so be sure to setup signing before you commit.

Use Husky

Ever wish you could stop people from committing changes that don’t pas linter and type checks? Well now you can. Husky allows you to run pre-commit checks that include linter and type checks to ensure the code being committed will pass static code analysis checks. This can be a huge time saver if you work with large teams where CI/CD is in place. A lot of time is eaten up by the build systems when people are allowed to commit to features branches that fail static code analysis checks. Here’s a basic example:

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "npm lint",
      "pre-push": "npm test",
      "...": "..."
    }
  }
}

Your CICD pipeline (and the people paying for it) will thank you.

Create Draft Pull Requests

Draft pull requests are a great way to avoid alerting code owners about changes that are not yet ready for a full review. This is useful if you want to see a summary of the commits and code changes, as well as have some pier review before forwarding to the wider team. To create a PR as a draft select the chevron on the create button and select “Create Draft Pull Request”.