Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/coverallsapp/github-action
Coveralls Github Action
https://github.com/coverallsapp/github-action
actions ci code-coverage code-quality test-coverage testing
Last synced: 27 days ago
JSON representation
Coveralls Github Action
- Host: GitHub
- URL: https://github.com/coverallsapp/github-action
- Owner: coverallsapp
- License: mit
- Created: 2019-08-05T17:07:14.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-06-12T23:30:11.000Z (5 months ago)
- Last Synced: 2024-10-06T02:01:57.450Z (about 1 month ago)
- Topics: actions, ci, code-coverage, code-quality, test-coverage, testing
- Homepage: https://coveralls.io
- Size: 20.7 MB
- Stars: 467
- Watchers: 11
- Forks: 75
- Open Issues: 73
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Coveralls GitHub Action
This GitHub Action posts your test suite's coverage data to [coveralls.io](https://coveralls.io/) 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.
## Usage
This action's step needs to run after your test suite has outputted a coverage report file. Most major test runners can be configured to do so, very likely with the adition of a test coverage library, such as `simplecov` for `ruby`, `coverage.py` for `python`, or `istanbul` or `jest` for `javascript`, etc.
### Inputs:
| Name | Requirement | Description |
| --------------------------- | ----------- | ----------- |
| `github-token` | _required_ | Default if not specified: `${{ github.token }}`. Can be also specified this way: `github-token: ${{ secrets.GITHUB_TOKEN }}`; Coveralls uses this token to verify the appropriate repo at Coveralls and send any new status updates based on your coverage results. This variable is built into Github Actions, so __do not add it to your secrets store__. [More Info](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token)|
| `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. |
| `files` | _optional_ | Default: all coverage files that could be found. Space-separated list of coverage report files produced by your test suite. Example: `files: coverage/test1.lcov coverage/test2.lcov` |
| `format` | _optional_ | Force coverage report 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 [supported coverage report formats list](https://github.com/coverallsapp/coverage-reporter#supported-coverage-report-formats). |
| `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://`; Specifies a [Coveralls Enterprise](https://enterprise.coveralls.io/) 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 filenames from your coverage reports correctly (e.g. packages/my-subproject) |
| `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. |
| `measure` | _optional_ | Default: `false`. Set to `true` to enable time time measurement logging. |
| `fail-on-error` | _optional_ | Default: `true`. Set to `false` to avoid CI failure when upload fails due to any errors. |
| `coverage-reporter-version` | _optional_ | Default: `latest`. Version of coverage-reporter to use. Make sure to prefix the version number with 'v'. For example: v0.6.9. Not available currently on macOS. |
### Outputs:
* `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](https://github.com/nickmerwin/node-coveralls)
```yaml
on: ["push", "pull_request"]
name: Test Coveralls
jobs:
build:
name: Build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Use Node.js 16.x
uses: actions/setup-node@v3
with:
node-version: 16.x
- name: npm install, make test-coverage
run: |
npm install
make test-coverage
- name: Coveralls
uses: coverallsapp/github-action@v2
```
### Complete Parallel Job Example:
```yaml
on: ["push", "pull_request"]
name: Test Coveralls Parallel
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
test_number:
- 1
- 2
steps:
- uses: actions/checkout@v4
- name: Use Node.js 16.x
uses: actions/setup-node@v3
with:
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/github-action@v2
with:
flag-name: run-${{ join(matrix.*, '-') }}
parallel: true
finish:
needs: test
if: ${{ always() }}
runs-on: ubuntu-latest
steps:
- name: Coveralls Finished
uses: coverallsapp/github-action@v2
with:
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.
## Demo
### 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.
## Troubleshooting:
### Coveralls comments aren't added to my pull request
Ensure that:
1. Your workflow invokes the Coveralls action runs on pull requests, e.g.:
```yaml
on: ["push", "pull_request"]
```
2. You have invited the [@coveralls](https://github.com/coveralls) user to your repository with `Role: Write`
3. 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*:
```yaml
github-token: ${{ secrets.GITHUB_TOKEN }}
```
---
## [MIT License](LICENSE.md)
## [Contributing](CONTRIBUTING.md)