Overview

The jacoco-badge-generator can be used in one of two ways: as a GitHub Action or as a command-line utility (e.g., such as part of a local build script). The jacoco-badge-generator parses a jacoco.csv from a JaCoCo coverage report, computes C0 and C1 coverage percentages from JaCoCo's Instructions and Branches counters, and generates badges for one or both of these (user configurable) to provide an easy to read visual summary of the code coverage of your test cases. The default behavior directly generates the badges internally with no external calls, but the action also provides an option to instead generate Shields JSON endpoints. It supports both the basic case of a single jacoco.csv, as well as multi-module projects in which case the action can produce coverage badges from the combination of the JaCoCo reports from all modules, provided that the individual reports are independent. It can also optionally generate a simple JSON summary report containing the computed coverages for easy consumption by other tools.

When used as a GitHub Action, the jacoco-badge-generator can also optionally be used as part of a pull-request check. Specifically, you can configure it to fail the workflow run if coverage decreased relative to prior run, and/or if coverage is below a target threshold.

The jacoco-badge-generator can be integrated directly into your CI/CD workflow within GitHub Actions, or it can be used as a command-line utility (installable for this purpose from PyPI). It is implemented in Python. The jacoco-badge-generator source code repository is hosted on GitHub; and is licensed under the MIT License. Also in the GitHub repository you will find detailed instructions for use including several sample GitHub workflows.

The jacoco-badge-generator GitHub Action is developed by Vincent A. Cicirello. It was originally implemented for my own use, but I have decided to share it with others.

Live GitHub Actions Examples

We have a template repository containing a simple Java project (Maven), and several runnable example workflows demonstrating the most common use-cases. The purpose of that repository is to enable potential new users of the action to use it as a project starter, or to have a sample that they can fork and experiment with before integrating into their projects.

You can also take a look at the following real projects that use the action.

Tech Stack

The jacoco-badge-generator GitHub Action utilizes the following:

• Python 3 (CLI mode is 100% Python with no external dependencies);
• GitHub Actions mode additionally utilizes the following:
  • The pyaction Docker container, which is a Docker container designed to support GitHub Actions development in the Python language (also see pyaction's GitHub repository);
  • The cicirello/python-github-action-template repository, a template that we maintain to assist developers getting started developing a GitHub Action in Python;
  • Docker since it is implemented as a container action; and
  • GitHub Container Registry, which is where we pull pyaction from at runtime for faster action loading (e.g., pulling the base Docker container from GitHub while an action is running on a GitHub server should be faster than pulling from Docker Hub).

Blog Posts About the jacoco-badge-generator

As the author of the jacoco-badge-generator, I occasionally post about this, and other software that I maintain on DEV.to. See my DEV.to profile for a full list of such posts. Below is a selection of blog posts specifically about the jacoco-badge-generator.

• JaCoCo Coverage Badges for Multi-Module Projects in GitHub Actions, posted on DEV on May 25, 2023.

  This post is a tutorial on usage of the jacoco-badge-generator for multi-module projects, including both within GitHub Actions as well as with the CLI utility.

• Using GitHub Actions to Build a Java Project With Pull Request Coverage Commenting and Coverage Badges, posted on DEV on November 9, 2022.

  This post is a tutorial on how to use GitHub Actions for a CI/CD pipeline to build a Java project, validate tests during pull requests, generate a coverage report, including commenting coverage on pull requests and generating coverage badges.

• The jacoco-badge-generator GitHub Action is now also available as a CLI tool from PyPI, posted on DEV on July 8, 2022.

  This post introduces an update to the jacoco-badge-generator that includes the ability to use as a command line tool, rather than strictly as a GitHub Action. Several examples of how to use the new functionality is covered, including how to install from PyPI.

• JaCoCo coverage badges, PR coverage checks, and PR coverage comments, from GitHub Actions, posted on DEV on November 29, 2021.

  This post introduces an update to the jacoco-badge-generator, which includes pull-request coverage checks. Additionally, it provides an example workflow demonstrating how to use it in combination with the GitHub CLI to automate commenting on pull requests with the test coverage. This workflow was a submission to the DEV/GitHub Actions Hackathon.