> ## 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.

# Automatic Coverage Setup

Qlty can set up code coverage reporting for a project by opening a pull request. Qlty Cloud's agent reads the project's CI configuration and test setup, adds the coverage upload step, and opens a draft pull request. You review it and merge it.

<Tip>Automatic setup is tested on GitHub Actions. On other CI providers it is best effort. See [Which CI providers it supports](#which-ci-providers-it-supports).</Tip>

## Before you start

* You need the **admin** role on the project.
* The [Qlty GitHub App](/cloud/github-app) must be installed on the repository. On GitHub Actions, it also needs the **Workflows** permission. That permission was added in September 2026, so if the app was installed earlier, an organization owner has to accept it. See [Accepting new permissions](/cloud/github-app#accepting-new-permissions).
* The project needs CI that runs automated tests. The agent adds a coverage upload step. It does not write tests.

## Setting up coverage

<Steps titleSize="h3">
  <Step title="Open the setup page">
    Go to **Project Settings > Code Coverage** and click **Set up coverage**. The page is also linked from the grey coverage shield on the project's Overview and in the projects list, for any project with no coverage yet.

    The **Automatic** tab is selected by default.
  </Step>

  <Step title="Click Set up automatically">
    Qlty starts a build and takes you to its page. The build usually takes a few minutes. When it finishes, the build page shows the result with a link to the pull request.

    If the Qlty GitHub App is not installed on the repository, or it is missing the Workflows permission, the page says so. The message links to the GitHub page that fixes it.
  </Step>

  <Step title="Review the draft pull request">
    The pull request is titled **Set up Qlty code coverage**. Qlty requests a review from you when GitHub allows it, which requires you to be a collaborator on the repository. Its description is the agent's report: what it changed, why, and anything you must do before merging.

    On GitHub Actions the upload authenticates with [OIDC](/coverage/tokens), so nothing is needed before merging. On other CI providers the pull request asks you to add a [coverage token](/coverage/tokens) as a CI secret. Add it before merging.

    Check the pull request's CI run for a successful upload. The upload step's log shows a line like `Line Coverage: 84.2%`.
  </Step>

  <Step title="Merge it">
    After the next CI run on your default branch, the project shows total coverage, per-file coverage grades, and line-by-line coverage. Reports arrive under **Project Settings > Code Coverage > Reports**.
  </Step>
</Steps>

## What the agent does

Qlty Cloud's agent runs in an isolated build container with a copy of your default branch and no Git credentials. It reads the CI configuration and the test setup, then reads these docs and makes the smallest change that produces complete coverage:

* Where coverage data is already generated, it adds only the upload step and points it at the existing output file.
* Where coverage data is not generated yet, it adds the minimum configuration to produce a report in a [supported format](/coverage/formats), passing flags from the CI workflow rather than editing the project's own scripts.
* Where a Qlty upload already exists, it repairs that upload if it is incomplete and otherwise makes no changes.
* Where several jobs or matrix entries produce different coverage, it uploads from each one and uses [server-side merging](/coverage/merging). Where CI runs test suites selectively, it uses [tags](/coverage/tags) instead.
* On GitHub Actions it uses the [Qlty GitHub Action](https://github.com/qltysh/qlty-action) with OIDC, and skips uploads on pull requests from forks, which have no OIDC token.

The agent cannot run your tests, install dependencies, or watch a CI run. It designs the change from the configuration and the docs, and the pull request says so. That is why the pull request is a draft: the first CI run on it is the test.

The agent never adds secrets, never adds test suites, and never sets `validate: false` to get past a path validation error.

## When the pull request's CI fails

Pull request CI failing or no report arriving usually means a path or format detail the agent could not check without running the tests. From the setup page, choose **Your agent** to run Qlty's open source [`setup-coverage` skill](https://github.com/qltysh/qlty-skills/tree/main/skills/setup-coverage) in your own coding agent. It can run your tests and iterate until CI passes. Or choose **Manual** and follow the [Coverage Quick Start](/coverage/quickstart).

## Which CI providers it supports

| CI provider | Support | How it uploads |
| - | - | - |
| GitHub Actions | Tested | Qlty GitHub Action with OIDC. No secret needed. |
| CircleCI | Best effort | [Qlty CircleCI Orb](https://circleci.com/developer/orbs/orb/qltysh/qlty-orb) with a workspace coverage token |
| Other providers | Best effort | Qlty CLI with a workspace coverage token |

"Best effort" means the agent follows the same approach, but we have not verified the results across these providers. Review the pull request with extra care, and expect to add the coverage token before merging.

## Build results

The build page shows one of these results:

* **Opened a pull request to set up code coverage.** Review and merge it.
* **No coverage changes were needed.** Coverage is already set up and correct, or the repository has no CI or tests to add coverage to. The agent's explanation is on the build page.
* **Coverage setup did not finish.** The run hit its cost or step limit, or ended with an error. Each run has a budget of 45 minutes. Start it again, or use **Your agent** or **Manual** setup.
* **Could not open a pull request.** Qlty could not push the branch or open the pull request on GitHub, usually because of a permission change. Check the GitHub App's permissions and start it again.

You can start setup again at any time from the same page.

## Data processing

To set up coverage, Qlty sends the contents of your repository's default branch to an AI subprocessor, currently Anthropic, together with your CI configuration and the Qlty docs the agent reads. The subprocessor does not train models on this data. See [Data Usage](/cloud/data-usage).

The agent runs with no Git or GitHub credentials, and it can only fetch pages from `docs.qlty.sh`, `docs.github.com`, and the CircleCI orb registry. The only way work leaves the container is the patch that Qlty turns into the pull request, which you review before anything runs on your default branch.

## Next steps

* [Coverage Quick Start](/coverage/quickstart) for manual setup, or to understand what the pull request changed
* [Coverage Tokens](/coverage/tokens) for OIDC and token authentication
* [Troubleshooting Code Coverage](/coverage/troubleshooting) if reports are sent but not arriving


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.