Code Coverage Tags

A coverage tag is a name attached to a coverage report, usually the name of the test suite that produced it. A commit can have one coverage report per tag, and a report can be built from one or more uploads. There are two primary reasons to use coverage tags:

To tell test suites apart. Qlty reports and gates coverage per tag, so you can see and enforce unit test coverage separately from end-to-end coverage, for example.
To keep total coverage accurate when not every commit or pull request runs every test suite. Qlty carries forward the most recent report for each tag that did not run, so total coverage and its comparisons stay complete.

Coverage tags or components?

Both features break coverage down into smaller pieces, but they work differently:

	Coverage tags	Components
Groups coverage by	Coverage report (for example, one tag per test suite)	File path
Created by	CI, automatically, the first time a report is published with the tag	Users, in project settings or through the API
Changed by	Editing the uploads in your CI configuration	Editing the component’s path patterns in Qlty
Commit statuses	One set per tag	None
When a commit has no data	Its most recent report is carried forward from an earlier commit	No carry forward
Effect of a stale entry	A tag that no longer receives reports is still carried forward until deleted	A component whose patterns match no files shows no coverage

The Code view also aggregates coverage for every directory without any configuration. Tags and components can be used together: tags describe which test suite produced the coverage, while components and directories describe which part of the codebase it covers.

Where tag coverage appears

When a project publishes tagged reports:

Commit statuses. Each tag reported for a pull request receives its own coverage gate (total coverage and/or diff coverage). Tags are currently the only way to publish more than one coverage commit status on a pull request.
Pull request comments. Each tag’s results appear in a separate section of the coverage summary comment.
Pull request coverage tab. Changes can be filtered by one or more tags.
Default branch. When browsing coverage for your default branch, the coverage presented combines all tags, and the views can also show coverage per tag.

Carry forward and selectively running test suites

If a commit has no report for a tag, Qlty carries forward the most recent report for that tag from an earlier commit. This is what makes tags work when a project runs its test suites selectively. Some CI setups run only some of a project’s test suites on a pull request by design. For example, a monorepo might run only the test suite for the service that changed, so a repository with three test suites runs one or two of them on a typical pull request. Without tags, Qlty compares the pull request’s coverage report against the base commit’s report as a whole. If the base ran all three suites and the pull request ran one, total coverage appears to drop, even though nothing was lost. With one tag per test suite, Qlty knows which suites a commit did and did not run. For the suites that did not run, it carries forward the most recent report for that tag, so total coverage comparisons stay complete.

Example: path-filtered workflows in a monorepo

Each workflow runs only when its service changes, and each publishes its own tag:

# .github/workflows/api.yml — runs only when api/ changes
on:
  pull_request:
    paths: ["api/**"]
# ...
- uses: qltysh/qlty-action/coverage@v2
  with:
    token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
    files: api/coverage/lcov.info
    tag: api

# .github/workflows/web.yml — runs only when web/ changes
on:
  pull_request:
    paths: ["web/**"]
# ...
- uses: qltysh/qlty-action/coverage@v2
  with:
    token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
    files: web/coverage/lcov.info
    tag: web

A pull request that changes only api/ publishes the api report. Qlty carries the web report forward from the most recent commit that published one, and compares the pull request’s combined coverage against the base commit’s combined coverage. Carry forward only comes into play when a commit lacks a report for a tag. If every suite ran on every pull request, each commit would have a report for both tags directly.

Publishing tagged coverage

Add the tag option to each upload. Every upload that contributes to a report carries the report’s tag.

# Unit test coverage
- uses: qltysh/qlty-action/coverage@v2
  with:
    token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
    files: coverage/unit/lcov.info
    tag: unit

# End-to-end test coverage
- uses: qltysh/qlty-action/coverage@v2
  with:
    token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
    files: coverage/e2e/lcov.info
    tag: e2e

# Unit test coverage
qlty coverage publish --tag=unit coverage/unit/lcov.info

# End-to-end test coverage
qlty coverage publish --tag=e2e coverage/e2e/lcov.info

There is nothing to define ahead of time. A tag is created the first time a report is published with its name. A few rules follow from tags being a property of the report:

Each upload carries one tag, or none. A commit can have one report per tag, plus one untagged report.
Use the same tag name for the same test suite on every commit. unit and unit-tests are two different tags, each tracked and carried forward on its own.
Tag names should not contain spaces or special characters.

Tags with report merging

Coverage tags work seamlessly with report merging, allowing complex workflows while maintaining tag-specific insights.

Important considerations

When using coverage tags with report merging:

Each qlty coverage publish command applies to a single tag (or no tag)
Merging always refers to combining reports for the same tag, not across different tags
Server-side merging requires tracking completion separately for each tag

Client-side merging with tags

With client-side merging, run the qlty coverage publish command once per tag, combining all reports for that tag:

# Publish unit test coverage (combining multiple reports)
- uses: qltysh/qlty-action/coverage@v2
  with:
    token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
    tag: unit
    files: |
        unit1.lcov
        unit2.lcov

# Publish integration test coverage (combining multiple reports)

- uses: qltysh/qlty-action/coverage@v2
  with:
    token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
    tag: integration
    files: |
        integration1.lcov
        integration2.lcov

# Publish unit test coverage (combining multiple reports)
qlty coverage publish --tag=unit \
    unit1.lcov unit2.lcov

# Publish integration test coverage (combining multiple reports)
qlty coverage publish --tag=integration \
    integration1.lcov integration2.lcov

Server-side merging with tags

For server-side merging, each tag must be handled independently.

Using `total-parts-count` with tags

When using the total-parts-count approach, specify the count separately for each tag:

# Integration tag example (1 of 4)
- uses: qltysh/qlty-action/coverage@v2
  with:
    token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
    tag: integration
    total-parts-count: 4
    files: coverage.lcov
# ... Three more `qltysh/qlty-action/coverage` steps for the `integration` tag ...

# Unit tag example (1 of 2)

- uses: qltysh/qlty-action/coverage@v2
  with:
    token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
    tag: unit
    total-parts-count: 2
    files: coverage.lcov

# ... One more `qltysh/qlty-action/coverage` step for the `unit` tag ...

# Integration tag example (1 of 4)
qlty coverage publish --tag=integration --total-parts-count=4 coverage.lcov
# ... Three more `qlty coverage publish` commands for the `integration` tag ...

# Unit tag example (1 of 2)
qlty coverage publish --tag=unit --total-parts-count=2 coverage.lcov
# ... One more `qlty coverage publish` command for the `unit` tag ...

Using `coverage complete` with tags

When using the --incomplete flag approach, upload parts for each tag and then send a completion signal for that specific tag:

qlty coverage publish --tag=unit --incomplete unit1.lcov
qlty coverage publish --tag=unit --incomplete unit2.lcov
qlty coverage complete --tag=unit

qlty coverage publish --tag=integration --incomplete integration1.lcov
qlty coverage publish --tag=integration --incomplete integration2.lcov
qlty coverage publish --tag=integration --incomplete integration3.lcov
qlty coverage complete --tag=integration

Managing tags

Tags persist once created. This is what allows coverage for each tag to be tracked consistently over time, even when the tag’s test suite does not run on every commit. It also means a tag that stops receiving reports does not go away on its own. Its last report keeps being carried forward onto newer commits and keeps counting toward the project’s coverage. When a test suite is retired or renamed, delete its old tag so that stale coverage stops being included.

Deleting tags

To remove a tag that is no longer in use:

Navigate to your project in Qlty Cloud
Go to Project Settings > Code Coverage
Find the tag in the list of coverage tags
Click the Delete button next to the tag name

Deleting a tag removes all historical coverage data associated with it.

Troubleshooting

Tag reporting issues

If you’re experiencing issues with tagged coverage reports:

Verify that the tag name is consistent across all commands
Ensure you’re providing the correct tag when using coverage complete commands
Check that the tag name doesn’t contain special characters or spaces

Missing tag data

If coverage data for a specific tag isn’t appearing:

Confirm that the coverage report was successfully uploaded
Verify that the correct tag was specified in the upload command
For reports using server-side merging, check that the completion signal was sent
Ensure all parts of a tagged report have been uploaded if using the total-parts-count approach

Getting Started

Coverage In Your Workflow

Concepts

Features

Advanced Configuration

Reference

Code Coverage Tags

Coverage tags or components?

Where tag coverage appears

Carry forward and selectively running test suites

Example: path-filtered workflows in a monorepo

Publishing tagged coverage

Tags with report merging

Important considerations

Client-side merging with tags

Server-side merging with tags

Using `total-parts-count` with tags

Using `coverage complete` with tags

Managing tags

Deleting tags

Troubleshooting

Tag reporting issues

Missing tag data

See Also

​Coverage tags or components?

​Where tag coverage appears

​Carry forward and selectively running test suites

​Example: path-filtered workflows in a monorepo

​Publishing tagged coverage

​Tags with report merging

​Important considerations

​Client-side merging with tags

​Server-side merging with tags

​Using total-parts-count with tags

​Using coverage complete with tags

​Managing tags

​Deleting tags

​Troubleshooting

​Tag reporting issues

​Missing tag data

​See Also

Coverage tags or components?

Where tag coverage appears

Carry forward and selectively running test suites

Example: path-filtered workflows in a monorepo

Publishing tagged coverage

Tags with report merging

Important considerations

Client-side merging with tags

Server-side merging with tags

Using `total-parts-count` with tags

Using `coverage complete` with tags

Managing tags

Deleting tags

Troubleshooting

Tag reporting issues

Missing tag data

See Also