Have you been wondering how some projects add a small badge to their README that shows the project build status ? Well we will show how to set this up on GitHub.
First this is documented in the official GitHub documentation : https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge and here https://docs.github.com/en/actions
However, the documentation may seem a bit daunting at first, so let’s make an easy to follow tutorial.
Setting up a build workflow
For this I will show how to build a very simple tool “devmem2” which was made to read and write /dev/mem from the command line. This program is quite old and does not work well on certain 64-bit architectures (e.g., ARM64) so I’ll use my fork which does support 64-bit architectures as an example.
The code is available here : https://github.com/rick-heig/devmem2
It is a simple, single .c file that can be compiled directly with GCC, or even be built by Make with an empty makefile (through built-in rules) like so :
# Compile with GCC
gcc devmem2.c -o devmem2
# Or compile with an empty Makefile
make -f /dev/null devmem2
Let’s add a GitHub action to build this automatically and show a badge in the README file.
On the GitHub page of the project press “Actions” (be sure to be signed-in).
Choose C/C++ with Make as an action.
This will open a suitable template
There is even a “Documentation” tab on the right to help you through. We will fill the workflow to compile devmem2 followed by a simple test that checks if the executable exists and is executable. Note that the name you choose here is the what will appear on the badge. So maybe choose something like “Build”.
Press “Commit changes…” and fill the commit message.
The action will now appear as a job under “Actions”.
If you click the job, and go into the details you can see what is going on.
You can click each step to see the command log, and if something goes wrong, find out why.
Adding the Badge to the README
We can now add the badge to the README.md as per the documentation it says to add the following to the Markdown readme :
This is the Markdown syntax to add images as described here. For our README it will be :
Once the change committed and pushed to GitHub, we can now see our badge :
A project instantly looks more professional with a badge !
Now that you have added your first badge, you will be compelled to add others, add one for your unit tests, add one for documentation generation, add one for when you had a coffee !