Commit Message Lint — Improve the Code Commit Quality
A GitHub App to enforce code commit standards
GitHub app are one of the preferred and better ways of implementing and improving your workflow. It provides a proven way of intercepting different DevOps phases related to your code and apply various checks. It enables you to perform linting checks, static code analysis, enforce commit strategies, and regulate pull requests. And these are just the most common actions. GitHub provides a variety of events which could be captured and actioned upon. And that is one of the places where you could apply some creativity.
We leveraged this powerful feature of GitHub to regulate our commit messages and pull request titles. Let’s take a look at the genesis of the idea, it’s execution and utilization of GitHub Apps in this.
Checkout the app on GitHub here. For a detailed step by step walkthrough on developing a Github app, checkout my previous article.
Problem Statement
As with most of the project these days, we follow Agile methodology for our projects. And the tool which helps us keep track of user stories and deliveries is JIRA. To keep the quality in check, we follow code review processes with the help of GitHub pull requests (referred to as PR from here on). This was going fine for us for a while.
Keeping Track of PR
After a while, with the increase in team size and deliverables, it became a sort of a pain for us to keep track of PRs themselves. There would be multiple developers working in parallel, some of them on different parts of a larger feature. This meant that there would be a number of PRs opened and waiting for merging.
To ease the process for the reviewers a bit, we integrated JIRA with GitHub workflow. And we asked the developers to put the JIRA ID in the commit ID and the PR title so that workflow would recognize the ticket which the PR belongs to. This helped us with two things:
- The GitHub workflow would recognize tickets in commits and PRs and process them accordingly.
- The reviewers would be able to recognize the PR, thereby prioritizing as per the business and technical needs.
The process surely looked promising from the outside. But soon we realized that there was a very basic flaw in this process. It relied on the developers to provide a valid commit message and PR title. And that was a problem for us. We wanted the developers to enter the messages and title in a very specific format.
Solution
The first thing which came to our mind was git hooks. Those would be a quick solution to fix the commit message format issues. But hooks have some inherent problems because of their local installation nature:
- They have to be installed on the developers machine.
- The onus relies with the developer to make sure they have installed the hooks.
- Every time a new developer joins, this becomes a part of their onboarding process.
- It’s difficult to update hooks, as they are not centralized.
- Adding a new capability into the hooks would mean going through the whole cycle from the start.
- Anybody can alter their local copy.
- They have a limitation in terms of actions they can perform.
- Their scope is limited to local repository.
- They cannot be used for continuous integration workflows.
With all these restrictions, we can safely say that hooks are more of a developer tool. But need something to enforce a strategy, or we can say a policy.
Enter GitHub Apps!!
GitHub apps provide a simple and straightforward mechanism to enforce and manage development policies. They are also recommended from GitHub itself because of the access and control they provide. It’s beneficial to use GitHub apps as:
- They provide granular permissions
- Access to repository events like PR creation, issue creation etc.
- Access to code itself, enabling us to perform tasks like linting, static code reviews etc.
- Central installation into the repository, providing more control.
- Easy to track app execution and issue from GitHub itself.
So GitHub app is what we used to solve our problem.
Commit Message Lint
As mentioned above, our requirement was to enforce a particular formatting on the commit messages and PR titles. So we built a GitHub app which would do this for us, as soon as a PR was generated.
GitHub Apps gave us the ability to perform multiple checks with just one code base. And this app was totally in our control. All we did was install the app in our repositories. From then on it would start appearing in PR checks, whenever a new PR was raised.
Following screenshots depict how the app displays in you repositories PRs.
Flow
Let’s take a look at the workflow once we have this app installed in our repository.
Features
We saw the core purpose of building the app. Let’s take a look at some of the key features:
Configuring the formats
The App allows you to configure separate formats which should be followed for PR titles and commit messages. These configurations need to be kept in your repository itself, providing the flexibility of having different formats per repository. And since they are present in the repository, they can be altered at any point, providing dynamic nature.
Look at this tutorial on how to configure the formats in your repository.
Pull Request Title Format check
The app will check for the PR title format:
- On the creation of PR: As soon as a PR is created, a check will be created in the checks section of PR. This will show the result of PR title validation in the form of success/failure.
- Re-run check: GitHub allows users to re-run a particular check, for example once the issues have been resolved. So in our case, if someone has updated the PR title as per the required format, they can re-run an existing check and view the results.
Commit Message format check
Similar to PR title check, the app checks for the format in commit messages. One PR can have multiple commits and all the commit messages are checked. Similar to PR title, commit messages are checked:
- On PR creation: When a new PR is opened.
- Re-run check: When the re-run check button is clicked.
Merging the PR
The PR ownership still resides with reviewer. The app does not enforce or block merging the PR. Based on the status of the check the reviewer has full discretion on whether to go ahead with the merge of ask the developer to make the changes.
Benefits we realized
So we developed the app, registered it on GitHub and published on GitHub marketplace. That’s all good. But what are the benefits we realized. Let’s take a look at some of them:
Setting up the app
- Setup the checks from GitHub in any repository, providing central control.
Configuration
- Easily configure the formats and update them as and when required.
Enforcing the format
- Reviewer does not have to worry about PR title or commit message. They would just look at the status of the check and make a decision.
- Speeds up the review process.
- Control resides at the repository level rather then with developers and reviewers.
- Easy to get developers onboard with no additional setup (like git hooks).
Improving the process
- With the automated check, it’s easier to follow and enforce the process.
- Setting up the process for new projects and repository is easy.
- Centrally manage and review the process.
Workflow automation
- With the enforcement of the process and required formats, integration with JIRA becomes easier and flawless.
- The overall workflow automation improves with lesser loopholes.
One less thing to worry about
- An important benefit which usually gets overlooked is that reviewers have one less thing to worry about. They can rely on the GitHub app to review the formats and let them know the results.
These were some of the benefits along with the most important one, integration with JIRA and automation workflow.
Summary
It sounds exciting to have an automated workflow in your project. But it’s when you try to implement it, you realize the pains involved. With manual controls involved at various places, your dream of a perfect workflow can go down the hill gradually.
There are tools which help us avoid these situations and improve not only our workflow and process, but also our team. The reviewers are better off when they have one less thing to worry about. They need to focus on the business logic and not the automation process. Let this app worry about your process and enforce the formats. This assists the developers to also improve their habits.
