Skip to content


Use this GitHub Action with your project

Add this Action to an existing workflow or create a new one.

View on Marketplace
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
April 24, 2023 11:04
August 6, 2019 17:01


Coveralls GitHub Action

This GitHub Action posts your test suite's LCOV coverage data to for analysis, change tracking, and notifications. You don't need to add the repo to Coveralls first, it will be created when receiving the post.

When running on pull_request events, a comment will be added to the PR with details about how coverage will be affected if merged.


The action's step needs to run after your test suite has outputted an LCOV file. Most major test runners can be configured to do so; if you're using Node, see more info here.


Name Requirement Description
github-token optional Default: ${{ github.token }}. Can be also used this way: github-token: ${{ secrets.GITHUB_TOKEN }}; Coveralls uses this token to verify the posted coverage data on the repo and create a new check based on the results. It is built into Github Actions and does not need to be manually specified in your secrets store. More Info
file optional Default: all coverage files that could be found. Local path to the coverage report file produced by your test suite. An error will be thrown if no file was found. This is the file that will be sent to the Coveralls API. Leave empty if you want to combine many files reports.
format optional Force coverage report file format. If not specified, coveralls will try to detect the format based on file extension and/or content. Possible values: lcov, simplecov, cobertura, jacoco, gcov, golang, python. See also actual supported coverage report formats list.
flag-name optional (unique required if parallel) Job flag name, e.g. "Unit", "Functional", or "Integration". Will be shown in the Coveralls UI.
parallel optional Set to true for parallel (or matrix) based steps, where multiple posts to Coveralls will be performed in the check. flag-name needs to be set and unique, e.g. flag-name: run ${{ join(matrix.*, ' - ') }}
parallel-finished optional Set to true in the last job, after the other parallel jobs steps have completed, this will send a webhook to Coveralls to set the build complete.
carryforward optional Comma separated flags used to carryforward results from previous builds if some of the parallel jobs are missing. Used only with parallel-finished.
coveralls-endpoint optional Hostname and protocol: https://<host>; Specifies a Coveralls Enterprise hostname.
allow-empty optional Default: false. Don't fail if coverage report is empty or contains no coverage data.
base-path optional Path to the root folder of the project the coverage was collected in. Should be used in monorepos so that coveralls can process the LCOV correctly (e.g. packages/my-project)
git-branch optional Default: GITHUB_REF environment variable. Override the branch name.
git-commit optional Default: GITHUB_SHA environment variable. Override the commit SHA.
compare-ref optional Branch name to compare coverage with. Specify if you want to always check coverage change for PRs against one branch.
compare-sha optional Commit SHA to compare coverage with.
debug optional Default: false. Set to true to enable debug logging.


  • coveralls-api-result: JSON response from the Coveralls API with a status code and url for the Job on Coveralls.

Standard Example:

  • This example assumes you're building a Node project using the command make test-coverage, demo here: nickmerwin/node-coveralls
on: ["push", "pull_request"]

name: Test Coveralls


    name: Build
    runs-on: ubuntu-latest

    - uses: actions/[email protected]

    - name: Use Node.js 16.x
      uses: actions/[email protected]
        node-version: 16.x

    - name: npm install, make test-coverage
      run: |
        npm install
        make test-coverage

    - name: Coveralls
      uses: coverallsapp/[email protected]

Complete Parallel Job Example:

on: ["push", "pull_request"]

name: Test Coveralls Parallel

    runs-on: ubuntu-latest
          - 1
          - 2
    - uses: actions/[email protected]
    - name: Use Node.js 16.x
      uses: actions/[email protected]
        node-version: 16.x

    - name: npm install
      run: npm install

    - name: Test ${{ matrix.test_number }}
      run: make test-coverage-${{ matrix.test_number }}
    - name: Coveralls Parallel
      uses: coverallsapp/[email protected]
        flag-name: run-${{ join(matrix.*, '-') }}
        parallel: true

    needs: test
    if: ${{ always() }}
    runs-on: ubuntu-latest
    - name: Coveralls Finished
      uses: coverallsapp/[email protected]
        parallel-finished: true
        carryforward: "run-1,run-2"

The "Coveralls Finished" step needs to run after all other steps have completed; it will let Coveralls know that all jobs in the build are done and aggregate coverage calculation can be calculated and notifications sent.



Steps shown:

  1. A new function f without test coverage is added.
  2. The changes are committed and pushed to a new branch "function/f"
  3. The workflow runs on GitHub Actions.
  4. The commit on GitHub shows a new check for Coveralls with details "First build on function-f at 92.0%", and links to the Job on Coveralls.
  5. Line-by-line results indicate the new function is missing coverage.
  6. Create a pull request with the new branch.
  7. The pull_request check runs and the resulting coverage data triggers a fail status.
  8. A detailed comment is posted.


Coveralls comments aren't added to my pull request

Ensure that:

  1. Your workflow invokes the Coveralls action runs on pull requests, e.g.:
on: ["push", "pull_request"]
  1. You have invited the @coveralls user to your repository as a collaborator
  2. You have enabled the "LEAVE COMMENTS?" setting in the "Pull Request Alerts" area in your Repo Settings page inside the Coveralls app.

Coveralls responds with "cannot find matching repository"

Ensure your workflow yaml line for the GitHub token matches exactly:

github-token: ${{ secrets.GITHUB_TOKEN }}

MIT License