Before I began actively using GitHub to work on my research publicly, I would sometimes end up on GitHub looking for a tool to accomplish some task or looking for a relevant library, etc. My first take on badges at the top of the README of a repository was along the lines of "what is this nonsense?", and I'd proceed to ignore that section of the README entirely. The more I've used GitHub I've discovered that in repositories where that section is well-organized and the badges linked to relevant information that it serves a very useful purpose. Essentially, the right mix of relevant and dynamic badges, displaying the right metadata, and linked to the right information becomes a TL;DR for your README. And with dynamic badges, the metadata is always up to date for the visitors of your repository without any intervention on your part.
TL;DR: Well-organized badges with relevant links == TL;DR for a repository's README.
The remainder of this post is organized as follows:
- What are badges?
- Where do I get them?
- Tips for using badges well
- Repository Used in Examples
- About Me
What are badges?
Here are a couple example badges from one of my projects, including how they are linked:
Without telling you anything you instantly know that the project publishes artifacts to Maven Central along with the latest version number, and you know the version of the latest GitHub release. If you follow the links, in the first case you end up on the Maven Central page for the library where you find all you need to import the library, and in the second case you end up on the releases tab of the GitHub repository.
Where do I get them?
There are three main sources of README badges: (1) badge generation services, (2) service specific badges, and (3) tools that you can run locally. Let's look at all three cases.
Badge generation services
Shields is probably the most widely used badge generation service. Another is Badgen. Shields has a larger variety with support for a wider variety of services, etc, but Badgen has a good variety as well, along with a few that Shields doesn't yet have. Most of these are dynamic badges, updating relevant information as things change (e.g., with new release version, build status, coverage percentage, etc). And both support both dynamic and static custom badges.
Service specific badges
Some services that you might use as part of your project may provide badges specific to their service. For example, if you use Zenodo to create DOIs for your releases, Zenodo provides a dynamic badge that updates with the DOI of the latest release, which you can link to the Zenodo archive of the release. Here is an example from the same project as above:
Snyk provides security score and vulnerability count badges, which you can link to the relevant pages, as in these examples:
Some badges may display static, yet still useful, metadata. For example, many of my repositories relate to my research, and as an academic also relate to journal articles I've published, such as an article in the Journal of Open Source Software, which provides each article with a badge that can be linked directly to the full-text of the article, such as:
Tools you can run yourself
In some cases, there may be tools that you can run yourself as part of your CI/CD workflows. For example, last week I posted about the jacoco-badge-generator, which can be used as either a GitHub Action or as a local CLI tool to parse a JaCoCo coverage report, generate coverage badges, as well as for performing PR checks. Here is a link to that DEV.to post:
Tips for using badges well
If you just grab the URLs for all of the badges even remotely relevant to your repository from Shields or Badgen, and just haphazardly place them at the top of your README without linking them to anything, they may detract from the readability of your repository's README, rather than improving it. I have two tips related to using badges well to provide a TL;DR that is useful to the visitors of your repository, as well as to yourself and any collaborators, specifically organization and link to relevant information.
Tip 1: Organization
If your project only has need for a few badges, perhaps five or less, just putting them in a row is probably sufficient. But if your README has more than that, it is worth thinking a bit about how to organize them. I've seen a variety of approaches to this that are effective. The approach that I take is with a markdown table with one row for each category of badge. Here is an example from one of my repositories (the very case I've used earlier for a few examples). Note that this example table looks differently here on DEV.to than it does on GitHub. They appear to process tables differently. It looks better on GitHub (for the intended purpose of this table).
| Publications About the Library | |
|---|---|
| Packages and Releases |
|
| Build Status |
  
|
| JaCoCo Test Coverage |
 
|
| Security |
|
| DOI | |
| License |  |
| Support |
  
|
Is this the only way to organize this set of badges? Of course not. Is this the best way to do so? Probably not. I've rearranged stuff as I've added to it, or as I've used it. For example, the metadata isn't just for visitors to your repository. It is there for you too.
If you like the table approach, I recommend using bold on the row labels because GitHub-flavored markdown tables use bold by default on the header row assuming that it consists in column headings. If you don't bold the row labels, then only the top row will have a bold row label. I also recommend either explicitly left aligning the columns or centering the columns. The example above is left aligned. The reason is that GitHub-flavored markdown by default centers the column headings, but not the contents of the columns. So if you leave it to the default, only the top row will be centered. The structure that I use for left alignment is as follows, which looks better on GitHub than here on DEV for the purpose of organizing badges.
| __Category One__ | badge markup with links here |
| :--- | :--- |
| __Category Two__ | badge markup with links here |
| __Category Three__ | badge markup with links here |
Or if you want to center everything, the following should work:
| __Category One__ | badge markup with links here |
| :---: | :---: |
| __Category Two__ | badge markup with links here |
| __Category Three__ | badge markup with links here |
Tip 2: Every Badge Should Link to Something Relevant
Visitors to your repository will likely click on some of your badges, expecting to be taken to more detailed information related to the metadata displayed in the badge. In the example table above, every badge links to something relevant. For some of these, what to link to is obvious (e.g., package repository badges, release badges, license badges, among others). For a few, it is slightly less so. For example, for build status badges for builds run on GitHub Actions, it would be nice if it was possible to link directly to the specific workflow run that corresponds to the displayed status. As far as I'm aware, that is not possible, so in my example, I have that linked to the list of runs of the relevant workflow, although in the case of the status of building the docs, I link to the live API docs that I serve from GitHub Pages instead.
The markup to link a build status badge to the corresponding list of workflow runs is as follows:
[](https://github.com/USERID/REPO/actions/workflows/WORKFLOW-FILE-NAME.yml)
GitHub actually generates a status badge for each of your GitHub Actions workflows, with a URL of the form:
https://github.com/USERID/REPO/workflows/NAME-OF-YOUR-WORKFLOW/badge.svg
You can combine the above two with:
[](https://github.com/USERID/REPO/actions/workflows/WORKFLOW-FILE-NAME.yml)
Repository Used in Examples
If you want to look at the examples within the broader context, as well as to see the actual result of formatting as a table as it appears on GitHub, all examples in this post are from the following repository.
cicirello
/
Chips-n-Salsa
A Java library of Customizable, Hybridizable, Iterative, Parallel, Stochastic, and Self-Adaptive Local Search Algorithms
Chips-n-Salsa - A Java library of customizable, hybridizable, iterative, parallel, stochastic, and self-adaptive local search algorithms
Copyright (C) 2002-2022 Vincent A. Cicirello.
Website: https://chips-n-salsa.cicirello.org/
API documentation: https://chips-n-salsa.cicirello.org/api/
| Publications About the Library |  |
|---|---|
| Packages and Releases |
  
|
| Build Status |
|
| JaCoCo Test Coverage |
|
| Security |
 
|
| DOI |  |
| License |  |
| Support |
  
|
How to Cite
If you use this library in your research, please cite the following paper:
Cicirello, V. A., (2020). Chips-n-Salsa: A Java Library of Customizable, Hybridizable, Iterative, Parallel, Stochastic, and Self-Adaptive Local Search Algorithms. Journal of Open Source Software, 5(52), 2448, https://doi.org/10.21105/joss.02448 .
Overview
Chips-n-Salsa is a Java library of customizable, hybridizable, iterative, parallel, stochastic, and self-adaptive local search algorithms. The library includes implementations of several stochastic local search algorithms, including simulated annealing, hill climbers, as well as constructive search algorithms such as stochastic sampling. Chips-n-Salsa now also includes genetic algorithms as well as evolutionary algorithms more generally. The library very extensively supports simulated…
About Me
Personal Website:
Vincent A. Cicirello - Professor of Computer Science
Vincent A. Cicirello - Professor of Computer Science at Stockton University - is a researcher in artificial intelligence, evolutionary computation, swarm intelligence, and computational intelligence, with a Ph.D. in Robotics from Carnegie Mellon University. He is an ACM Senior Member, IEEE Senior Member, AAAI Life Member, EAI Distinguished Member, and SIAM Member.
cicirello.org
DEV.to Profile:
GitHub Profile:
Vincent A Cicirello
| Sites where you can find me or my work | |
|---|---|
| Web and social media |
  
|
| Software development |
   
|
| Publications |
      
|
If you want to generate the equivalent to the above for your own GitHub profile, check out the cicirello/user-statistician GitHub Action.
Top comments (1)
Super indepth article. I often wondered where repositorys got there badges from. Well now I know. Thank you for sharing 🚀