> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qlty.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Coverage Quick Start

This guide will help you set up code coverage reporting in your CI pipeline.

## Prerequisites

1. A repository with automated tests that generate coverage data
2. A GitHub user with administrator permissions on your organization
3. Ability to modify and run CI scripts for your repository

## Step 1. Determine an authentication approach

Qlty supports three ways to authenticate code coverage uploads from your CI system:

1. OpenID Connect (OIDC) with GitHub Actions (recommended)
2. Workspace-level coverage tokens
3. Project-level coverage tokens

If you are using GitHub Actions, we recommend using OIDC as it is the most secure and requires no management of long-lived coverage tokens.

If not using OIDC, a workspace-level token is the next most convenient, followed by project-specific tokens.

## Step 2. Store the coverage token as a CI secret

*If you are using OIDC, you can skip this step. (OIDC is tokenless)*

### Obtain a Coverage Token

* Login to Qlty via GitHub OAuth
* Navigate to *Workspace Settings > Code Coverage* (e.g. `https://qlty.sh/gh/your-org/settings/coverage`)
* Copy the workspace's coverage token

### Provide Coverage Token in Environment

A coverage token should be treated as a credential and stored securely within your CI system.

The specifics for how to store a secret at the organization level vary by provider:

* [GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions)
* [CircleCI](https://circleci.com/docs/contexts/)
* [Buildkite](https://buildkite.com/docs/pipelines/security/secrets/buildkite-secrets)
* [Travis CI](https://docs.travis-ci.com/user/encryption-keys/)

## Step 3. Update CI workflow scripts

This guide assumes that your CI scripts are already generating code coverage data from the execution of your automated tests. The method to generate this data varies by programming language and testing tools.

Once you have code coverage data being generated in one of our [supported formats](/coverage/generating-data), continue with the steps below.

### GitHub Actions

Add a step to run the `qltysh/qlty-action/coverage` reusable GitHub Action:

<CodeGroup>
  ```yaml OIDC-based authentication (recommended) lines theme={"system"}
  # ...
  permissions:
      contents: read
      id-token: write # IMPORTANT

  jobs:
      build:
          # ...
          steps:
              # ...

              - uses: qltysh/qlty-action/coverage@v2
                with:
                    oidc: true
                    files: coverage/lcov.info # REPLACE WITH PATH TO YOUR COVERAGE FILE
  ```

  ```yaml Token-based authentication lines theme={"system"}
  # ...
  jobs:
      build:
          # ...
          steps:
              # ...

              - uses: qltysh/qlty-action/coverage@v2
                with:
                    token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
                    files: coverage/lcov.info # REPLACE WITH PATH TO YOUR COVERAGE FILE
  ```
</CodeGroup>

<Note>
  The Qlty GitHub Action is simply a convenience wrapper that installs the qlty CLI and executes `qlty coverage publish` with the provided arguments.

  If you are unable to use the Qlty Github Action (because your organization's security policy does not permit it, or you are using a self-hosted runner), using the Qlty CLI directly is straight-forward. See CLI Integration below.
</Note>

<Warning>
  The Qlty GitHub Action is **not supported on self-hosted runners.** If you’re on self-hosted
  runners, use the Qlty CLI to upload coverage instead.
</Warning>

### CircleCI Orb

We provide a CircleCI Orb for uploading coverage reports. Add the following to your `.circleci/config.yml` file:

```yaml lines theme={"system"}
# ...
jobs:
    run_tests_and_publish_coverage:
        # ...
        steps:
            # ...
            - qlty-orb/coverage_publish:
                  files: coverage/lcov.info
```

[Learn more about our CircleCI Orb](https://circleci.com/developer/orbs/orb/qltysh/qlty-orb)

<Note>
  The Qlty CircleCI Orb is a convenience wrapper that simply installs the qlty CLI and executes `qlty coverage publish` with the provided arguments.

  If you are unable to use the Qlty CircleCI Orb manual integration is straight-forward. See CLI Integration below.
</Note>

### CLI Integration

If you are not using CircleCI or GitHub, or prefer not to use the convenience wrappers available for those providers, using the Qlty CLI in your workflow is simple and supported on any CI provider.

To publish coverage, you will install the Qlty CLI and run the `qlty coverage publish` command, specifying the coverage data file(s):

```bash lines theme={"system"}
# Assumes $QLTY_COVERAGE_TOKEN is set in the environment
curl https://qlty.sh | sh
qlty coverage publish coverage/lcov.info # Replace with path to your coverage data file(s)
```

<Tip>
  For security-sensitive environments, you can [verify the CLI's
  integrity](/cli/integrity-verification) before installation.
</Tip>

Occassionally, `qlty coverage publish` requires additional arguments. The most commonly used arguments are:

* `--add-prefix` and/or `--strip-prefix` to ensure the paths to source files are valid
* `--format` to specify the format of the coverage file (e.g. `--format jacoco`)

See our documentation on [CI Integration](/coverage/ci) for more information.

## Step 4. Validate coverage uploads from a branch

After updating your CI script:

1. Push your changes to a branch and trigger a build
2. Ensure the build completes successfully with no errors during the upload process
3. On Qlty, navigate to your *Project Settings > Code Coverage* page
4. Your uploaded coverage report should appear in the table at the bottom of the page
5. Click on the commit SHA to view your report details and verify it matches your expectations

## Step 5. Merge your CI script changes into your main branch

Once coverage uploads are working successfully for your branch:

1. Merge the branch into your main branch and run a build
2. Ensure the build completes successfully with no errors from the coverage upload step
3. Validate the coverage upload in your Project Settings
4. Once Qlty receives a valid coverage report for your main branch, your coverage info will be displayed in your project's Overview page

## Optional: Enable coverage commit statuses

To enforce coverage thresholds on pull requests:

* Enable commit statuses (**Qlty Coverage** and **Qlty Diff Coverage**) within your Project's Gate settings
* Adjust coverage check settings (including configurations for minimum diff size and total coverage decrease)

## Next Steps

* [Generating Coverage Data](/coverage/generating-data) - Format-specific configuration
* [Coverage Metrics](/coverage/metrics) - Learn about the coverage metrics Qlty provides
* [Coverage Merging](/coverage/merging) - Merge multiple coverage reports from parallel test runs
* [Example Repositories](/coverage/example-repositories) - Reference implementations
* [Troubleshooting](/coverage/troubleshooting) - Common issues and solutions