go-beautiful-html-coverage

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

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

[!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.

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