{"id":15765426,"url":"https://github.com/cicirello/examples-jacoco-badge-generator","last_synced_at":"2025-04-21T03:32:05.417Z","repository":{"id":38289662,"uuid":"396940543","full_name":"cicirello/examples-jacoco-badge-generator","owner":"cicirello","description":"Sample Java project with runnable workflows demonstrating the cicirello/jacoco-badge-generator GitHub Action","archived":false,"fork":false,"pushed_at":"2024-09-03T22:21:56.000Z","size":104,"stargazers_count":3,"open_issues_count":0,"forks_count":10,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-05T12:41:43.609Z","etag":null,"topics":["coverage","github-actions","jacoco","jacoco-badge-generator","maven","testing"],"latest_commit_sha":null,"homepage":"https://actions.cicirello.org/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cicirello.png","metadata":{"funding":{"github":"cicirello","patreon":null,"open_collective":null,"ko_fi":"cicirello","tidelift":null,"community_bridge":null,"liberapay":"cicirello","issuehunt":null,"otechie":null,"custom":null},"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-16T19:25:08.000Z","updated_at":"2024-09-03T22:21:54.000Z","dependencies_parsed_at":"2023-12-15T01:23:26.975Z","dependency_job_id":"61b72a7c-92d7-45f0-9366-0ef4ec199f0b","html_url":"https://github.com/cicirello/examples-jacoco-badge-generator","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Fexamples-jacoco-badge-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Fexamples-jacoco-badge-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Fexamples-jacoco-badge-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Fexamples-jacoco-badge-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cicirello","download_url":"https://codeload.github.com/cicirello/examples-jacoco-badge-generator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249991063,"owners_count":21357196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coverage","github-actions","jacoco","jacoco-badge-generator","maven","testing"],"created_at":"2024-10-04T12:41:43.057Z","updated_at":"2025-04-21T03:32:05.095Z","avatar_url":"https://github.com/cicirello.png","language":"Java","funding_links":["https://github.com/sponsors/cicirello","https://ko-fi.com/cicirello","https://liberapay.com/cicirello"],"categories":[],"sub_categories":[],"readme":"# Runnable Workflows Demonstrating the [cicirello/jacoco-badge-generator](https://github.com/cicirello/jacoco-badge-generator) GitHub Action\n\nThe purpose of this repository includes:\n* providing a simple example of configuring the jacoco-maven-plugin,\n* providing a simple example of running jacoco in GitHub Actions as part of a build, and\n* providing runnable example workflows using the \n  [cicirello/jacoco-badge-generator](https://github.com/cicirello/jacoco-badge-generator) GitHub \n  Action.\n  \n## Why is this Repository a Template?\n\nI made this repository a template to make it easy for someone\nto use it to get started on a new project. To use this to start a \nnew project, click the \"Use this Template\" button. Depending on\nwhich starter workflow you want to use, you might want to select \nthe option to include all branches. If you are not sure, then\nfor now include all branches. You can always delete unneeded\nbranches afterwards.\n\nYou are also free to fork this repository if you want (e.g.,\nif you want to contribute to it with a pull request or for some \nother reason, such as just trying out the workflows). Keep in mind,\nhowever, that GitHub by default disables workflows in forks. So if you\nfork the repository for the purpose of experimenting with the action\nand the provided sample workflows, then you will need to enable GitHub \nActions via the actions tab of your fork.\n\n## Before You Modify Anything\n\nAll of the sample workflows are configured to run on pushes and pull requests.\nSo if you change anything, all of the sample workflows will run. A couple of them\nwrite the same files, so if you change any of the Java files in a way that would\nchange the coverage percentages or if you delete the badges so you can fully watch\nthe action work, then when the workflows attempt to push you \nwill probably end up with conflicts. If you don't change the Java files, no conflicts will\noccur because the existing badges won't change, so the workflows won't attempt to push\nanything.\n\n**Recommendation:** If you want to explore the effects of modifying anything, start by\ncommenting out the push and pull request events that trigger all of the workflows except \nwhichever one is closest to your desired use-case).\n\n## The Maven pom.xml\n\nThe `pom.xml` in this repository builds a very simple program, a weird variation\nof Hello World, with convoluted logic to artificially create a test coverage example.\nIf you are new to using the `jacoco-maven-plugin` then take a look at how it\nis configured. It will generate all of the variations of the JaCoCo coverage\nreport (\"html\", \"csv\", and \"xml\"). It is configured to run during the test phase.\n\n## Building Locally\n\nTo build and test locally, run either of the following command at the root\nof the repository:\n\n```Shell\nmvn clean test\n```\nor\n\n```Shell\nmvn clean package\n```\n\nThe latter will generate a jar, while the former will not. The tests\nand test coverage reports run in both cases. Since we are really focused on\ntest coverage here, we don't really need the jar.\n\n## Where are the Test Coverage Reports?\n\nAssuming you ran the build locally (see above), the build would have created\na `target` directory (Maven's default). The target directory is in the `.gitignore`\nto ensure we don't commit any of that to the repository. \nYou will find the JaCoCo reports at the following path: `target/site/jacoco`. \nDouble-click the `index.html` file you see there to inspect the html version of \nthe coverage report, which is most useful for a human viewer. It is the `jacoco.csv`\nfile, however, that \nthe [cicirello/jacoco-badge-generator](https://github.com/cicirello/jacoco-badge-generator) \nGitHub Action uses, which is far simpler to parse.\n\n## Summary of What the Workflows Do\n\nThe [.github/workflows](.github/workflows) directory contains several\nexample workflows that use\nthe [cicirello/jacoco-badge-generator](https://github.com/cicirello/jacoco-badge-generator) \nGitHub Action. If you are new to GitHub workflows, they must be in that directory in order \nto run. Each workflow also contains comments explaining all of the steps of each. Here is \na brief summary of each.\n\n### Basic case: [.github/workflows/build.yml](.github/workflows/build.yml)\n\nThis is the basic use-case, which generates both the coverage\nand branches coverage badges storing them in the default directory,\n.github/badges. The workflow runs on pushes, pull requests, and can\nbe run manually (the workflow_dispatch event). Here are the badges\nit produces:\n\n![coverage](.github/badges/jacoco.svg)\n![branches coverage](.github/badges/branches.svg)\n\nThe above was inserted into this README with the following\nmarkdown:\n\n```markdown\n![coverage](.github/badges/jacoco.svg)\n![branches coverage](.github/badges/branches.svg)\n```\n\nIf your main branch is protected and includes either required checks or\nrequired reviews, then the push step will fail. To get around this, one \noption is to see GitHub's documentation on using a personal access token (PAT)\nwith the actions/checkout step. This is not at all an issue if your branch \nis protected, but doesn't have required checks or reviews. In that case, the \ndefault GITHUB_TOKEN is sufficient for the push, and a PAT is not needed.\n\nWe personally do not like the use of a PAT for circumventing required\nchecks or reviews. After all, if you have put those in place, you have done so\nfor a reason. And once you have the PAT in place in the repository, anyone\nwith write access to the repository can then use it in additional workflows\nto bypass those protections.  Therefore, some of the other sample workflows\ndemonstrate alternatives that do not require additional access.\n\n### Pull Request to Update Badges: [.github/workflows/build-pr.yml](.github/workflows/build-pr.yml)\n\nThis example is nearly identical to the basic case above. The only difference\nis that instead of committing and pushing the badges, it uses\nanother action to generate a pull request to update the badges.\n\nWhy? Well, this is the simplest approach to dealing with a protected branch that has\nrequired checks and/or required reviews. The drawback is that you must then\napprove and merge the pull request, so this variation introduces a manual step.\nHowever, it is more secure than introducing a PAT.\n\nIf you use this approach, and use the default directory for the badges, and the default\nbadge filenames, then you insert the badges into your README with the same markdown\nas the previous example:\n\n```markdown\n![coverage](.github/badges/jacoco.svg)\n![branches coverage](.github/badges/branches.svg)\n```\n\n### Dedicated Badges Branch: [.github/workflows/build-badges-branch.yml](.github/workflows/build-badges-branch.yml)\n\nIn the previous example, using a PR to updated badges is less than ideal since it\nintroduced an extra manual step. An alternative that eliminates that extra step,\nand which also works with protected branches without the need for extra access\npermissions, is to use a dedicated branch to store the badges. In this example,\nwe do just that, and that branch has been named `badges`. This workflow pushes the\nbadges to the `badges` branch. If you are using this\napproach in an existing project, you'll need to start by creating the `badges` branch.\nThis repository already has it. Once you create the `badges` branch you can delete\neverything from it. In fact, it is preferable that you delete everything from the\n`badges` branch.\n\nThis workflow assumes that the only purpose of the `badges` branch is to store the coverage\nbadges, so we'll store them at the root of that branch. The `badges` branch can be protected\nif you want. Just don't add any required checks or reviews to the `badges` branch. The \ndefault GITHUB_TOKEN can push to protected branches as long as there are no required checks \nor required reviews.\n\nThe important thing to notice in this workflow is the pair of checkout steps at the beginning.\nThe first is the usual checkout step. The second checks out the `badges` branch, nesting it\nwithin the other in the path `badges`. In this way, locally within the remainder of the\nworkflow run, we can access the content of the `badges` branch via the local `badges`\ndirectory.\n\nHere are the badges that result from this workflow:\n\n![coverage](../badges/jacoco.svg)\n![branches coverage](../badges/branches.svg)\n\nThe above badges were inserted with the following markdown:\n\n```markdown\n![coverage](../badges/jacoco.svg)\n![branches coverage](../badges/branches.svg)\n```\n\nThe reason for the weird `../badges` in the above links is so that\nwe can use relative links, but GitHub automatically assumes the\ncurrently viewed branch of the README with relative links so we can\ngo up one level to back out of the current branch and then go into the\nbadges branch. \n\nDo we really need the two checkout steps? Can't we just use one of the\nother available GitHub Actions that have the ability to push to a different\nbranch than the one currently checkout out?  Well, the answer depends upon\nwhether you are using the optional feature of \nthe [cicirello/jacoco-badge-generator](https://github.com/cicirello/jacoco-badge-generator) \nGitHub Action that enables you to use the action as a PR check, and to specify whether or \nnot to fail the workflow run if coverage has decreased. If you are not using that\nfeature, then you can choose to either do it this way anyway, or to use another\napproach to pushing to the `badges` branch. If you are using that feature, however,\nthen you will need to check out both branches in this way. This is because that\nfeature relies on the prior badges to determine if coverage has decreased\n(e.g., it parses those badges for the prior coverage and branches coverage). \n\n### JSON Endpoints Instead of SVG: [.github/workflows/build-json.yml](.github/workflows/build-json.yml)\n\nThis example is a variation of the basic use-case, but instead of\ndirectly generating the SVGs, it instead generates JSON endpoints \nin the format expected by Shields custom badge endpoint. Just like the\nbasic use-case, it uses the default directory `.github/badges`.\n\nInserting the badges into your project's README becomes a bit more complex\nin this case. You must pass the URL of the JSON file to Shields as a URL\nquery parameter. In particular, you must pass the URL of the JSON file on \nGitHub's raw server.\n\nHere are the badges as generated by Shields from the JSON endpoints:\n\n![coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cicirello/examples-jacoco-badge-generator/main/.github/badges/jacoco.json)\n![branches coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cicirello/examples-jacoco-badge-generator/main/.github/badges/branches.json)\n\nThe above badges were inserted with the following markdown:\n\n```markdown\n![coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cicirello/examples-jacoco-badge-generator/main/.github/badges/jacoco.json)\n![branches coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cicirello/examples-jacoco-badge-generator/main/.github/badges/branches.json)\n```\n\nThe general format of the markdown required is as follows:\n\n```markdown\n![coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/USERNAME/REPOSITORY/BRANCHNAME/.github/badges/jacoco.json)\n![branches coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/USERNAME/REPOSITORY/BRANCHNAME/.github/badges/branches.json)\n```\n\nYou unfortunately can't use relative paths since you need to pass the full URL to\nShields. And thus, if you have created a repository from this template or forked the\ntemplate repository, the example badges in this section are actually still derived from\nthe endpoints in the original template repository.\n\nIn most cases, you will probably prefer to use the default behavior that directly\ngenerates the badges since serving the badges in that case only requires one http\nrequest per badge, while the alternative that involves passing endpoints to Shields\ninvolves two requests per badge (one to Shields, and then a second initiated by Shields\nto your endpoint). But one advantage of using the endpoint approach is that it\ngains you access to all of Shields's built-in customizations. For example, if you wanted\nto use one of their alternate styles, you can select that as an additional URL parameter.\n\nHere is an example that directs Shields to use the Shields style \"for-the-badge\", rather\nthan the default \"flat\" style:\n\n![coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cicirello/examples-jacoco-badge-generator/main/.github/badges/jacoco.json\u0026style=for-the-badge)\n![branches coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cicirello/examples-jacoco-badge-generator/main/.github/badges/branches.json\u0026style=for-the-badge)\n\nThe markdown that was used for the above badges is as follows:\n\n```markdown\n![coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cicirello/examples-jacoco-badge-generator/main/.github/badges/jacoco.json\u0026style=for-the-badge)\n![branches coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/cicirello/examples-jacoco-badge-generator/main/.github/badges/branches.json\u0026style=for-the-badge)\n```\n\nIf your main branch has required checks or required reviews, then this workflow will\nfail during the push step. You can easily adapt either of the previous approaches to\ndealing with that to the endpoint case (e.g., either having the workflow generate a\npull request, or pushing the endpoints to a different branch). In the latter case,\nyou will need to adjust the markdown to pass the appropriate URL to Shields.\n\n### JSON Endpoints from a GitHub Pages Project Site\n\nWe do not have a specific sample workflow for this case. We don't have GitHub Pages active\non this repository. However, it is a straightforward combination of the previous\ntwo examples.\n\nFirst, you will take the approach from the example of the \"Dedicated Badges Branch\",\nbut name the branch `gh-pages`. Second, go into settings for the repository and follow\nGitHub's directions for enabling GitHub Pages, specifically to serve from that branch.\nYou might then include other content about your project in this branch such as API documentation,\netc.\n\nNext, modify the \"Dedicated Badges Branch\" workflow to generate the JSON endpoints\ninstead of directly generating the badges, as was done in the previous example\n\"JSON Endpoints Instead of SVG\", as well as to change the `badges-directory` to whatever\npath you used on the checkout of the dedicated `gh-pages` branch.\n\nAssuming you didn't enable a custom domain on your project site, the URL to the\nroot of this project site will be of the form:\n\n```\nhttps://USERNAME.github.io/REPOSITORY\n```\n\nIf you stored the JSON files in the root of the `gh-pages` branch, then the URLs\nto these files will be:\n\n```\nhttps://USERNAME.github.io/REPOSITORY/jacoco.json\nhttps://USERNAME.github.io/REPOSITORY/branches.json\n```\n\nNote that it is very important that you don't use the default badges directory of\nyour `gh-pages` branch because directories and files that start with `.` are not\naccessible from GitHub Pages.\n\nBy using GitHub Pages in combination with the JSON endpoints, we can slightly\nsimplify the markdown needed to have Shields generate the badges, to the following:\n\n```markdown\n![coverage](https://img.shields.io/endpoint?url=https://USERNAME.github.io/REPOSITORY/jacoco.json)\n![branches coverage](https://img.shields.io/endpoint?url=https://USERNAME.github.io/REPOSITORY/branches.json)\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcicirello%2Fexamples-jacoco-badge-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcicirello%2Fexamples-jacoco-badge-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcicirello%2Fexamples-jacoco-badge-generator/lists"}