Skip to content

A GitHub Action to track code coverage in your pull requests, with a beautiful HTML preview, for free.

License

Notifications You must be signed in to change notification settings

gha-common/go-beautiful-html-coverage

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

49 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

go-beautiful-html-coverage

Mentioned in Awesome Go

A GitHub Action to track code coverage in your pull requests, with a beautiful HTML preview ↗, for free.

Buy Me A Coffee

Usage

To use this action simply add it to your pre-existent ci workflow. A bare minimal example might look like this:

name: Go

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  test:
    name: Build and Test
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write        # required for posting comments
      contents: write             # required for git push
    steps:
      - uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5

      - name: Test                # this should generate cover.out
        run: make test

      - name: Go Beautiful HTML Coverage
        uses: 'gha-common/go-beautiful-html-coverage@v1'

How it works

This GHA expects cover.out to be present in the root of your repo at runtime. cover.out is usually generated by go test when passing the -coverprofile=cover.out flag:

go test -coverprofile=cover.out ./...

For examples on how you might do that you can peak at go-test-app/Makefile, or some of my other go projects like pretender and base-go-cli.

Once your test has ran and cover.out has been generated, the GHA does the following:

  1. Create and push new orphan branch if one doesn't exist.
  2. Generate cover.html and cover.txt from cover.out.
  3. Customize cover.html and rename it <sha>.html.
  4. git-push the <sha>.html file to the orphan branch. This will trigger a GitHub Pages deployment.
  5. Post a comment to your PR with your code coverage summary (cover.txt) and a link to your <sha>.html.

Screenshots


PR Comment HTML Preview (Dark) HTML Preview (Light)

Note

In order for the HTML preview links to work, configure GitHub Pages in your target repo (Settings > Pages) to Deploy from a branch and pick your target branch, which is, by default, cover.

GitHub Pages Setup

Reference

- name: Go Beautiful HTML Coverage
  uses: 'gha-common/go-beautiful-html-coverage@v1'
  with:
    # Repository name with owner. For example, actions/checkout.
    # Default: ${{ github.repository }}
    repository: ''

    # The branch to checkout or create and push coverage to.
    # Default: 'cover'
    branch: ''

    # The token to use for pushing to the repository.
    # Default: ${{ github.token }}
    token: ''

    # The relative path of your go project. Useful for monorepos and custom folder structures.
    # Default: ./
    path: ''

    # The minimum % of coverage required.
    # Default: 0
    threshold: ''

Examples

You can customize the name of the branch that hosts the code coverage files.

- name: Go Beautiful HTML Coverage
  uses: 'gha-common/go-beautiful-html-coverage@v1'
  with:
    branch: 'my-coverage'

Just make sure to update the GitHub Pages deployment settings to match.

You can customize the repository that hosts the code coverage files.

This is helpful if you don't want to clutter your project's repo, or if you want to centralize coverage reporting across multiple repos, or you can't turn on GitHub Pages in your project's repo.

- name: Go Beautiful HTML Coverage
  uses: 'gha-common/go-beautiful-html-coverage@v1'
  with:
    repository: yourname/coverage
    token: ${{ secrets.GHA_COVERAGE_TOKEN }}

Where GHA_COVERAGE_TOKEN is a repository secret with a personal token that has write access to yourname/coverage.

You can customize the path to your go project in the repo.

This is helpful if you have a monorepo with multiple apps, or simply you keep your go files in a subfolder. Just make sure to generate cover.out for all your apps before running this GHA.

- name: Go Beautiful HTML Coverage
  uses: 'gha-common/go-beautiful-html-coverage@v1'
  with:
    path: ./go-app-01

- name: Go Beautiful HTML Coverage
  uses: 'gha-common/go-beautiful-html-coverage@v1'
  with:
    path: ./go-app-02

License

MIT License, see LICENSE