Forem: Eyar Zilberman

A Deep Dive Into Kubernetes Schema Validation

Eyar Zilberman — Tue, 01 Jun 2021 10:24:16 +0000

Why run schema validation?

How do you ensure the stability of your Kubernetes clusters? How do you know that your manifests are syntactically valid? Are you sure you don’t have any invalid data types? Are any mandatory fields missing?

Most often, we only become aware of these misconfigurations at the worst time - when trying to deploy the new manifests.

Specialized tools and a “shift-left” approach make it possible to verify a Kubernetes schema before they’re applied to a cluster. In this article, I'll address how you can avoid misconfigurations and which tools are best to use.

TL;DR

Running schema validation tests is important, and the sooner the better.

If all machines (local developers environment, CI, etc.) have access to your Kubernetes cluster, run kubectl --dry-run in server mode on every code change. If this isn’t possible, and you want to perform schema validation tests offline, use kubeconform together with a policy enforcement tool to have optimal validation coverage.

Available tools

Verifying the state of Kubernetes manifests may seem like a trivial task, because the Kubernetes CLI (kubectl) has the ability to verify resources before they’re applied to a cluster. You can verify the schema by using the dry-run flag (--dry-run=client/server) when specifying the kubectl create or kubectl apply commands, which will perform the validation without applying Kubernetes resources to the cluster.

But I can assure you that it’s actually more complex. A running Kubernetes cluster is required to obtain the schema for the set of resources being validated. So, when incorporating manifest verification into a CI process, you must also manage connectivity and credentials to perform the validation. This becomes even more challenging when dealing with multiple microservices in several environments (prod, dev, etc.).

Kubeval and kubeconform are command-line tools that were developed with the intent to validate Kubernetes manifests without the requirement of having a running Kubernetes environment. Because kubeconform was inspired by kubeval, they operate similarly — verification is performed against pre-generated JSON schemas that are created from the OpenAPI specifications (swagger.json) for each particular Kubernetes version. All that remains to run the schema validation tests is to point the tool executable to a single manifest, directory or pattern.

Comparing

kubeval
kubeconform
kubectl dry-run in ‘client’ mode
kubectl dry-run in ‘server’ mode

Now that we covered the tools that are available for Kubernetes schema validation, let’s compare some core abilities (misconfigurations coverage, speed test, different versions support, CRD support and docs).

Misconfigurations coverage¹

I donned my QA hat and generated some (basic) Kubernetes manifest files with some intended misconfigurations, and then ran it against all four tools²:

Misconfig/Tool	kubeval / kubeconform	kubectl dry-run in ‘client’ mode	kubectl dry-run in ‘server’ mode
API deprecation	✅ Caught	✅ Caught	✅ Caught
Invalid kind value	✅ Caught	❌ Didn't catch	🚧 Caught³
Invalid label value	❌ Didn't catch	❌ Didn't catch	✅ Caught
Invalid protocol type	✅ Caught	❌ Didn't catch	✅ Caught
Invalid spec key	✅ Caught	✅ Caught	✅ Caught
Missing image	❌ Didn't catch	❌ Didn't catch	✅ Caught
Wrong K8s indentation	✅ Caught	✅ Caught	✅ Caught

Conclusion: Running kubectl dry-run in ‘server’ mode caught all misconfigurations, while kubeval/kubeconform missed two of them. It’s also interesting to see that running kubectl dry-run in ‘client’ mode is almost useless because it’s missing some obvious misconfigurations, and also requires a connection to a running Kubernetes environment.

Benchmark speed test

I used hyperfine to benchmark the execution time of each tool⁴. First I ran it against (1) all the files with misconfigurations (seven files in total), and then I ran it against (2) 100 Kubernetes files (all the files contain the same config).

(1) Results for running the tools against seven files with different Kubernetes schema misconfigurations:

(2) Results for running the tools against 100 files with valid Kubernetes schemas:

Conclusion: We can see that while kubeconform (#1), kubeval (#2) and kubectl --dry-run=client (#3) are providing fast results on both tests, while kubectl --dry-run=server (#4) is working slower, especially when it needs to evaluate 100 files — 60 seconds for generating a result is still a good outcome in my opinion.

Kubernetes versions support

Both kubeval and kubeconform accept the Kubernetes schema version as a flag. Although both tools are similar (as mentioned, kubeconfrom is based on kubeval), one of the key differences between them is that each tool relies on its own set of pre-generated JSON schemas:

Kubeval - instrumenta/kubernetes-json-schema (last commit: 133f848 on April 29, 2020)
Kubeconform - yannh/kubernetes-json-schema (last commit: a660f03 on May 15, 2021)

As of today (May 2021), kubeval only supports Kubernetes schema versions up to 1.18.1, while kubeconform supports the latest Kubernetes schema available today — 1.21.0. With kubectl, it’s a little bit trickier. I don’t know which version of kubectl introduced the dry-run, but I tried it with Kubernetes version 1.16.0 and it still worked, so I know it’s available in Kubernetes versions 1.16.0-1.18.0.

The variety of Kubernetes schemas support is especially important if you want to migrate to a new Kubernetes version. With kubeval and kubeconform you can set the version and start the process of evaluating which configurations must be changed to support the cluster upgrade.

Conclusion: The fact that kubeconform has all the schemas for all the different Kubernetes versions available — and also doesn’t require minikube setup (as kubectl does) — makes it a superior tool when comparing these capabilities to its alternatives.

Other things to consider

Custom Resource Definition (CRD) support
Both kubectl dry-run and kubeconform support resource type CRD, while kubeval does not. According to kubeval docs, you can pass a flag to kubeval to ignore missing schemas, so it will not fail when testing a bunch of manifests for which only some are resource type CRD.

Documentation
Kubeval is a more popular project than kubeconform, and therefore, its community and documentation are more extensive. Kubeconform doesn't have official docs but it does have a well-written README file that explains pretty well its capabilities. The interesting part is that although Kubernetes native tools, like kubectl, are usually well-documented, it was really hard to find the necessary information needed to understand how the dry-run flag actually works and its limitations.

Conclusion: Although it’s not as famous as kubeval, the CRD support and good-enough documentation make kubeconform the winner in my opinion.

Comparison summary

Item/Tool	kubeval	kubeconform	dry-run client	dry-run server
Misconfigurations coverage	+/-	+/-	-	+
Benchmark speed test	+/-	+	+/-	-
Kubernetes versions support	-	+	+/-	+/-
CRD support	-	+	+	+
Documentation	+	+/-	-	-

Now that you know the pros and cons associated with each tool, here are some best practices for how to best leverage them within your Kubernetes production-scale development flow.

Strategies for validating Kubernetes schema using these tools

⬅️ Shift-left: When possible, the best setup is if you can run kubectl --dry-run=server on every code change, but you probably can’t do it because you can’t allow every developer or CI machine in your organization to have a connection to your cluster. So, the second-best effort is to run kubeconform.
🚔 Because kubeconform doesn’t cover all common misconfigurations, it’s recommended to run it with a policy enforcement tool on every code change to fill the coverage gap.
💸 Buy vs. build: If you enjoy the engineering overhead, then kubeconform + conftest is a great combination of tools to get good coverage. Alternatively, there are tools that can provide you with an out-of-the-box experience to help you save time and resources, such as Datree⁵ (whose schema validation is powered by kubeconform).
🚀 During the CD step, it shouldn’t be a problem to have a connection with your cluster, so you should always run kubectl --dry-run=server before deploying your new code changes.
👯 Another option for using kubectl dry-run in server mode, without having a connection to your Kubernetes environment, is to run minikube + kubectl --dry-run=server. The downside of this hack is that it’s also required to set up the minikube cluster like prod (same volumes, namespace, etc.) or you’ll encounter errors when trying to validate your Kubernetes manifests.

GRATITUDE

Thank you to Yann Hamon for creating kubeconform - it’s awesome!
This article wouldn’t be possible without you. Thank you for all of your guidance.

All the schemas validation tests performed against Kubernetes version 1.18.0 ↩
Because kubeconform is based on kubeval, they provide the same result and run them against the files with the misconfigurations. kubectl is one tool but each mode (client or server) produces a different result as you can see from the table ↩
Server mode didn’t mark the file as valid (exit code 1) but the error message is wrong: Kind=pod doesn't support dry-run ↩
All benchmark test performed on my MacBook Pro with a 2.3 GHz Quad-Core Intel Core i7 processor ↩
Disclaimer - self-promotion here :) ↩

💻 Coding your way out of the Coronavirus 🚑

Eyar Zilberman — Tue, 17 Mar 2020 00:38:04 +0000

Disclaimer: The following post includes unfunny jokes about the Coronavirus (COVID-19) and the Corona crisis. Some people may find this content offensive, so continue reading at your own risk. This blog should not be taken seriously under any circumstances.

The Coronavirus is creating shock waves around the world, forcing more developers to work from home. While the practices to avoid the Coronavirus spread among humans is pretty clear for most of us, this blog will cover the best practices to avoid your code from being infected (prevention), checking to see if your code is infected (detection) and what to do in the case of contamination (post-infection). It is also important to remember that the statistics show us that new (freshly developed) code has a higher chance of recovery after infection. Legacy code (any code that was created before the year 2010) is at the high-risk group.

✋ Prevention

Due to the high infection rate and the fact that Alibaba AI didn’t create the anti-coronavirus, all experts agree that the best cure, for now, is prevention.

Avoid using protocols that require handshaking

Handshaking is the most common way to establish an exchange of information between two machines. Unfortunately, this is also the most common way to get infected and to spread the Coronavirus. Therefore, try to avoid using protocols that require handshaking to start communication (e.g. TCP, TLC, etc.)

Be careful when copying code from crowded places

Crowded places like stack overflow and open source projects, especially the ones with plenty of contributors, have more chances to contain code that is infected by the Coronavirus. Instead, try to copy code from your teammates, unpopular open-source projects, and bad stack overflow answers.

Achieve (and maintain) code hygiene

Now it is the best time to stop writing “quick-and-dirty” and to start refactoring, so you will have clean code because keeping high code hygiene standards will help to avoid infection. Also, be sure to verify you’re sanitizing (any) input data received, especially if it received from external services.

🔎 Detection

If your code is acting funky, maybe it is not because you’re a sh*ty developer, but because you got infected. It is crucial to constantly debug, monitor and scan your code with different anti-viruses solutions (like VirusTotal) to check your code health.

😱 Post-infection

If you find that your code got contaminated, you should follow the guides under this section ASAP!

Git blame to see how you got infected

Thanks to the ability to use git blame it is possible to detect how your code got infected so the relevant safety measurements can be taken to prevent the spread of the Coronavirus.

Use only localhost to serve your app

Infected code should stay in quarantine until fully recovered. Therefore, if your app contains code with Coronavirus, for public safety, it should be accessible only on the localhost and not exposed to the world.

Mask your IP in public places

Contrary to the myth that masks should protect you from getting infected, they are actually supposed to help infected code not to infect other code snippets out there. So if you MUST deploy your code on the WWW, at least mask your server IP to minimize the exposure to others.

FYI, I followed all those practices and my code is Corona free since 93'.

10 insanely useful Git commands you wish existed – and their alternatives

Eyar Zilberman — Tue, 23 Apr 2019 13:43:50 +0000

There’s a git command for that

Git commands aren’t always intuitive. If they were, we would have these 10 commands at our disposal. They would be super useful for accomplishing common tasks like creating or renaming a git branch, removing files, and undoing changes.

For each git command in our wishlist, we’ll show you the commands that actually exist and you can use to accomplish the same tasks. If you’re still learning Git, this list reads like a tutorial and is worth keeping as a cheatsheet.

# 9 – git create branch: create a new branch with git checkout

The fastest way to create a new branch is to actually do it from the git terminal. This way you don’t have to use GitHub UI, for example, if you use GitHub for version control.

This command actually exists in git, only in a different name – $ git checkout.

How to create a branch with git checkout:

One-line command: $ git checkout -b <branch-name> master

-> commit-test git:(master) $ git checkout -b feature-branch master
-> commit-test git:(feature-branch) $

Git tip: Just like with commit messages, having a naming convention for git branches is a good best practice to adopt.

# 8 – git force pull: overwrite local with git pull

You find out you’ve made changes that seemingly conflict with the upstream changes. At this point, you decide to overwrite your changes instead of keeping them, so you do a $ git pull and you get this error message:

-> commit-test git:(master) $ git pull
Updating db40e41..2958dc6
error: Your local changes to the following files would be overwritten by merge:
README.md
hint: Please, commit your changes before merging.
fatal: Exiting because of unfinished merge.

How to overwrite local changes with git pull:

Stash local changes: $ git stash
Pull changes from remote: $ git pull

-> commit-test git:(master) $ git stash
Updating db40e41..2958dc6
Saved working directory and index state WIP on master: d8fde76 fix(API): remove ‘test’ end-point
-> commit-test git:(master) $ git pull
Auto-merging README.md
Merge made by the ‘recurive’ strategy.
README.md     | 1 +
ENDPOINT.js    | 3 ++–
2 files changes, 3 insertions(+), 1 deletions(-)

Git tip: If you want to retrieve your changes just do: $ git stash apply

# 7 – git remove untracked files: delete untracked files from working tree

When having unnecessary files and dirs in your own local copy of a repository, and you want to delete those files, in opposed to just ignore them (with .gitignore), you can use git clean to remove all files which are not tracked by git.

How to remove untracked files and dirs:

Start with a dry-run to see what will be deleted: $ git clean -n -d
After you are sure, run the git clean command with “-f” flag: $ git clean -f -d

-> commit-test git:(master) $ git clean -n -d
Would remove dontTrackDir/untracked_file1.py
Would remove untracked_file2.py
-> commit-test git:(master) $ git clean -f -d
Removing dontTrackDir/untracked_file1.py
Removing untracked_file2.py

Git tip: Instead of untracking files, a good practice is to prevent those files from being tracked in the first place by using .gitignore file.

# 6 – git unstage: unstage file(s) from index

When you’re adding files ($ git add) to the working tree, you are adding them to the staging area, meaning you are staging them. If you want Git to stop tracking specific files on the working tree, you need to remove them from your stage files (.git/index).

How to unstage file(s) from index:

Keep the file but remove it from the index: $ git rm --cached <file-name>

-> commit-test git:(master) $ git rm –cached unstageMe.js
rm unstageMe.js

To leave the entire working tree untouched, unstage all files (clear your index): $ git reset

-> commit-test git:(master) $ git reset

Git tip: you can also untrack files which already added to git repository based on .gitignore.

# 5 – git undo merge: abort (cancel) a merge after it happened

Sometimes you get in a situation (we’ve all been there) where you merged branches and realize you need to undo the merge because you don’t want to release the code you just merged.

How to abort (cancel) a merge and maintain all committed history:

Checkout to the master branch: $ git checkout master
Run git log and get the id of the merge commit: $ git log --oneline
Revert merge by commit id: $ git revert -m 1 <merge-commit-id>
Commit the revert and push changes to the remote repo. You can start putting on your poker face and pretend “nothing’s happened”.

-> commit-test git:(master) $ git log –oneline
812d761 Merge pull request #524 from datreeio/DAT-1332-resolve-installation-id
b06dee0 feat: added installation event support
8471b2b fix: get organization details from repository object

-> commit-test git:(master) $ git revert -m 1 812d761
Revert “Merge pull request #524 from datreeio/DAT-1332-resolve-installation-id”
[master 75b85db] Revert “Merge pull request #524 from datreeio/DAT-1332-resolve-installation-id”
1 file changed, 1 deletion(-)
-> commit-test git:(master) $ git commit -m “revert merge #524”
-> commit-test git:(master) $ git push

Git tip: Instead of reverting merge, working with pull requests and setting up or improving your code review process can lower the possibility of a faulty merge.

# 4 – git remove file: remove file(s) from a commit on remote

You wish to delete a file (or files) on remote, maybe because it is deprecated or because this file not supposed to be there in the first place. So, you wonder, what is the protocol to delete files from a remote git repository?

How to remove file(s) from commit:

Remove your file(s): $ git rm <file-A> <file-B> <file-C>
Commit your changes: $ git commit -m "removing files"
Push your changes to git: $ git push

-> commit-test git:(delete-files) $ git rm deleteMe.js
rm ‘deleteMe.js’
-> commit-test git:(delete-files) $ git commit -m “removing files”
[delete-files 75e998e] removing files
1 file changed, 2 deletions(-)
delete mode 100644 deleteMe.js
-> commit-test git:(delete-files) $ git push

Git tip: When a file is removed from Git, it doesn’t mean it is removed from history. The file will keep “living” in the repository history until the file will be completely deleted.

# 3 – git uncommit: undo the last commit

You made a commit but now you regret it. Maybe you committed secrets by accident – not a good idea – or maybe you want to add more tests to your code changes. These are all legit reasons to undo your last commit.

How to uncommit (undo) the last commit:

To keep the changes from the commit you want to undo: $ git reset --soft HEAD^
To destroy the changes from the commit you want to undo: $ git reset --hard HEAD^

-> commit-test git:(undo-commit) $ git commit -m “I will regret this commit”
[undo-commit a7d8ed4] I will regret this commit
1 file changed, 1 insertion(+)
-> commit-test git:(undo-commit) $ git reset –soft HEAD^
-> commit-test git:(undo-commit) $ git status
On branch undo-commit
Changes to be committed:
(use “git reset HEAD <file>…” to unstage)

    modified: README.md

Git tip: Git pre-commit hook is a built-in feature that lets you define scripts that will run automatically before each commit. Use it to reduce the need to cancel commits.

# 2 – git diff between branches

When you are working with multiple git branches, it’s important to be able to compare and contrast the differences between two different branches on the same repository. You can do this using the $ git diff command.

How to get the diff between two branches:

Find the diff between the tips of the two branches: $ git diff branch_1..branch_2
Produce the diff between two branches from common ancestor commit: $ git diff branch_1...branch_2
Comparing files between branches: $ git diff branch1:file branch2:file

-> commit-test git:(diff-me) $ git diff master..diff-me
diff –git a/README.md b/README.md
index b74512d..da1e423 100644
— a/README.md
+++ b/README.md
@@ -1,2 +1,3 @@
# commit-test
-Text on “master” branch
+Text on “diff-me” branch

Git tip: diff-so-fancy is a great open source solution to make your diffs human readable.

# 1 – git delete tag: remove a tag from branch

In the case of a “buggy” release, you probably don’t want someone to accidentally use the release linked to this tag. The best solution is to delete the tag and remove the connection between a release and its co-related tag.

How to delete tag by removing it from branch:

If you have a remote tag to delete, and your remote is origin, then simply: $ git push origin :refs/tags/<tag-name>
If you also need to delete the tag locally: $ git tag -d <tag-name>

-> commit-test git:(delete-tag) $ git push origin :refs/tags/v1.0.0
To github.com:datreeio/commit-test.git
– [deleted]         v1.0.0
-> commit-test git:(delete-tag) $ git tag -d v1.0.0
Deleted tag ‘v1.0.0’ (was af4d0ea)

Git tip: Not sure when or why to use tags? Read here to learn more (TL;DR: automatic releasing)

# 0 – git rename branch: change branch name

As I mentioned, having a branch naming convention a good practice and should be adopted as part of your coding standards, and it is especially useful in supporting automation of git workflows. But what to do when you find out your branch name is not aligned with the convention, after already pushing code to the branch? Don’t worry, you can still rename your branch.

How to rename branch name after it was created:

Checkout to the branch you need to rename: $ git checkout <old-name>
Rename branch name locally: $ git branch -m <new-name>
Delete old branch from remote: $ git push origin :<old-name> <new-name>
Reset the upstream branch for the new branch name: $ git push origin -u <new-name>

-> commit-test git:(old-name) $ git branch -m new-name
-> commit-test git:(new-name) $ git push origin :old-name new-name
Total 0 (delta 0), reused 0 (delta 0)
To github.com:datreeio/commit-test.git
–  [deleted]             old-name
* [new branch]      new-name -> new-name
-> commit-test git:(new-name) $ git push origin -u new-name
Branch new-name set up to track remote branch new-name from origin.
Everything up-to-date

Git tip: Want to make sure all branch names will always follow your convention? Set a Git-enforced branch naming policy.

What's next?

Found some useful commands? you can also set alias commands for them!
Relevant alias to this blog post are provided by @mfrata in his comment - you can thank him :)

Originally posted on https://datree.io/resources/git-commands

Top 10 GitHub Best Practices

Eyar Zilberman — Mon, 15 Apr 2019 13:28:03 +0000

After scanning thousands of repositories and interviewing hundreds of GitHub, I created a list of common best practices which are strongly recommended to be adopted in every modern software development organization which is using GitHub to store their code:

9. 🚧 Protect the main branches from direct commits

Anything in the master branch should always be deployable, that’s why you should never commit to the default branches directly and why Gitflow workflow has become the standard. Using branch protection can help you prevent direct commits and of course, everything should be managed via pull requests.

8. 👻 Avoid unrecognized committers

Maybe you are working on a new environment, or you didn’t notice that your Git configuration is incorrect which causes the user to commit code with the wrong email address. Now, their commit is not associated with the right user and makes it nearly impossible to trace back who wrote what.

Make sure that your Git client is configured with the correct email address and linked to your GitHub user. Check your pull requests during code review for unrecognized commits.

7. 🎩 Define CODEOWNERS for each repository

Using the CODEOWNERS feature allows you to define which teams and people are automatically selected as reviewers for the repository. This ability automatically requests a review from the repository owners. Nowadays organizations have dozens if not hundreds of repositories and CODEOWNERS gives the option to define who the repo maintainers are across your organization.

6. 🙊 Separate secret credentials from source code

When building a Cloud Native app, there are many secrets — account passwords, API keys, private tokens, and SSH keys — that we safeguard. NEVER! commit any secrets into your code. Instead, use environment variables that are injected externally from a secure store.

You can use tools like Vault and AWS Secrets Manager to help with your secret management in production.

There are lots of great tools to identify existing secrets in your code and prevent new ones. For example, Git-secrets can help you to identify passwords in your code. With Git Hooks you can build a pre-commit hook and check every pull request for secrets.

5. ⛔ Avoid committing dependencies into your project

Pushing dependencies into your remote origin will increase repository size. Remove any projects dependencies included in your repositories and let your package manager download them in each build. if you are afraid of “dependencies availability” you should consider using a binary repository manager solution like Jfrog or Nexus Repository. Also, check out Git-Sizer by GitHub.

4. 🔧 Separate configuration files from source code

We strongly recommend against committing your local config files to version control. Usually, those are private configuration files which you don’t want to push to remote because they are holding secrets, personal preferences, history or general information which should stay only in your local environment.

📤 3. Create a meaningful .gitignore file for your projects

A .gitignore file is a must in each repository to ignore predefined files and directories. It will help you to prevent secret keys, dependencies and many other possible discrepancies in your code. You can choose a relevant template from Gitignore.io.

2. 💀 Archive dead repositories

Over time, for various reasons, we find ourself with unmaintained repositories. Maybe you opened a new repository for an ad hoc use case (or you wanted to POC a new tech) or you have some repositories with old and irrelevant code. The problem is the same – those repositories are not actively developed anymore after they served their purpose, so you don’t want to maintain them or other people will rely on/use them. The best practice will always be to archive those repositories which will make them “read-only” to everyone.

1. 🔒 Lock package version

Your manifest file holds the information about all of your packages versions to maintain consistent results without breaking your code every time you install your app dependencies. The best practice is to use a manifest lock file to avoid any discrepancies and confirm that you are getting the same packages version each time. The opposite being that you leave your code component version imprecise, are uncertain which version will be installed on the next build and your code may break.

0. ♻️ Align packages versioning

Although you are using the same package, a different version distribution will make it harder to reuse code and tests in various projects.

If you have a package which is used in multiple projects, try at a minimum to use the same major version across the different repositories.

🚀 What’s next?

All that’s left for you to do is check off each of the aforementioned best practices, on each of your repositories, one by one.

Or, save your sanity and connect with Datree’s GitHub app (it's even free!) to scan your repositories and generate your free status report to assess if your repositories align with the listed best practices.

How to Get More Out of Your Git Commit Message

Eyar Zilberman — Thu, 28 Mar 2019 12:06:00 +0000

Git commit message

If you aren’t already, defining your project Git commit message convention is always on every developer’s “To-Do” list. Like flossing your teeth – everyone knows it’s necessary best practice for healthy gums and avoiding the dentist, but it ends up on the ‘I’ll move it to tomorrow’s to-do list’ aka, procrastination galore.

I’m going to break down the reasons why you really have NO excuse not to set a Git commit message convention (or floss), and the required steps in order to move this task from your “To-Do” list to “DONE” in a few simple steps!

I’ll leave your dentist to yell at you about not flossing 😁

Why use a commit message convention?

Better collaboration between potential and existing committers

It is important to communicate the nature of changes in projects in order to foster transparency to a slew of people: existing teammates, future contributors, and sometimes to the public and other stakeholders. It’s obvious why a well-formatted Git commit message convention is the best way to communicate context about a change to fellow developers (and their future selves) when requesting a peer code review. A commit message convention also makes it easier to explore a more structured commit history and to understand which notable changes have been made between each release (or version) of the project.

Squeeze the most out of git utilities

“$ git log” is a beautiful and useful snippet. A well-organized commit message history leads to more readable messages that are easy to follow when looking through the project history. Suddenly, navigating through the log output become a possible mission! Embracing a commit message convention will also help you properly use other git commands like git blame, git revert, git rebase, git shortlog and other git subcommands.

Support different automation tools

Automation, automation, automation. Once you know you can rely on a standardized Git commit message, you can start building a flow around it and leverage the power of automation to level-up your project development flow:

Automatic generation of CHANGELOG – keeps everyone up to date on what happened between releases.
Automatic bump ups to the correct version – determine a release semantic version based on the types of commits made per release.
Automatic triggers to other processes – you are only limited by your own imagination on this one. For example, you can decide that a predefined string in the commit message will trigger your CI.

Choosing the right commit message convention

Now that we know that having a commit message convention is useful whether you’re working on an open source project, working on your own, or working with your team on a single project, standardizing the Git commit message is the only right way to commit!

We covered the “why” part and now we will move to the “how” part – in my opinion, there are pretty much only two ways to go:

A. Adopt defacto best practices

This approach is a simple and easy guideline, good for getting used to the idea of having a convention/have a majority of coders or junior developers on the team. It’s the top 5 best practices to implement TODAY:

Have a commit message – white space or no characters at all can’t be a good description for any code change.
Keep a short subject line – long subjects won’t look good when executing some git commands. Limit the subject line to 50 characters.
Don’t end the subject line with a period – it’s unnecessary. Especially when you are trying to keep the commit title to under 50 characters.
Start with a capital letter – straight from the source: “this is as simple as it sounds. Begin all subject lines with a capital letter”.
Link to a planning system – if you are working with a planning system (like Jira), it is important to create a logical link between the planning ticket number and the subsequent code change.

B. Adopt an existing conventions framework

This approach is relevant for advanced/engaged teams, the key benefit of this approach is that you can also use the supporting tools in the ecosystem of the chosen conventions. There are plenty of different conventions so I will focus on the top two:

Angular Git commit message guidelines – well known and proven Git commit message convention which was introduced by the Angular project (A.K.A. Google).
Emoji Git commit message convention – I’m not kidding, it’s a thing. Incorporating emoji in the commit message is an easy way of identifying the purpose or intention of a commit at a glance, and of course, emoji are fun 😜. Because this convention is a philosophy and not a method, if chosen, I would recommend “Emoji-Log” commit message convention (by Ahmad Awais).

How to enforce Git commit message?

If you got this far, you probably agree with my opinion that every project should have a defined commit message convention. Now, the question is how can I make sure all the project committers (me, outside contributors and teammates) are aligned about the chosen convention and apply to it? My top two solutions for that are:

🔧 1. Git hooks

🚔 2. Server-side policy enforcement

Both options explained with a guide on my original blog post (I didn't add it here to keep this post short).