How to collect and publish code coverage

aspect test --coverage collects Bazel code coverage as part of a normal test run and hands the merged LCOV report to a tool of your choice — an HTML generator locally, a service like Codecov in CI.

How this relates to `bazel coverage`

bazel coverage is Bazel’s own command for this: it “builds and runs the specified test targets using the specified options while collecting code coverage statistics,” and it accepts everything bazel test accepts. aspect test --coverage arrives at the same place from the test side. It runs bazel test and sets the coverage flags for you, so Bazel does the same work and writes the same merged LCOV report to the same path. You don’t invoke bazel coverage yourself, and you don’t add a second Bazel pass to get coverage out of a run that was already testing. Going through the task rather than calling Bazel directly gets you two things:

It’s still the test task. BES streaming, status checks and MR signal, test-log upload, automatic retries on transient Bazel failures, and --task-key all keep working. A raw bazel coverage invocation has none of that wrapped around it.
The report gets handled. --coverage-report and --coverage-tool resolve the merged report’s real path and hand it off. Doing that by hand is the fiddly part, because Bazel’s convenience symlinks make the same report easy to discover twice.

Together that makes aspect test --coverage a more natural and convenient way to get coverage than a traditional bazel coverage run. And because it is bazel test underneath, your normal test flags and tag filters apply unchanged.

Collecting coverage

--coverage adds --collect_code_coverage and --combined_report=lcov to the Bazel invocation. Bazel merges per-test coverage into a single LCOV report at $(bazel info output_path)/_coverage/_coverage_report.dat.

aspect test --coverage -- //...

Add --coverage-report=PATH to copy that report somewhere predictable for a later step, creating parent directories as needed:

aspect test --coverage --coverage-report=coverage/lcov.dat -- //...

Bazel only instruments targets matching --instrumentation_filter. If files you expected are missing from the report, widen it with --bazel-flag=--instrumentation_filter=^//.

Publishing the report

--coverage-tool runs a binary against the report once testing finishes. --coverage-tool-arg supplies its arguments — repeat the flag once per argument — and {report} (or {lcov}) is substituted with the report’s absolute path. If no argument contains the placeholder, the path is appended as the last argument. Both flags need --coverage; on their own they do nothing. Three behaviors are worth knowing before you put this in a pipeline:

The tool runs whether or not the tests passed, so an uploader still publishes partial coverage from a failing run — without a separate always-run step to arrange.
A non-zero exit from the tool is a warning, not a failure. A rejected upload leaves the build green, so watch for --coverage-tool: ... exited with code N on stderr rather than trusting a passing job.
If Bazel produced no report, the tool is skipped with a warning. That usually means nothing matched, nothing was instrumented, or the rules in play don’t support coverage.

A local HTML report needs nothing else:

aspect test --coverage \
  --coverage-tool=genhtml \
  --coverage-tool-arg=--output-directory=coverage-html \
  -- //...

Codecov

There are two routes. Option 1 runs the Codecov binary from the test task and behaves identically on every CI platform. Option 2 writes the report to a file and lets your platform’s own Codecov integration upload it, which fits repos that already have Codecov wired up that way. Whichever you pick, turn Codecov’s file search off. Left on, it scans the working directory for coverage files and follows Bazel’s convenience symlinks, so it reports the same merged file more than once — once under bazel-out and once under the workspace path that links to it — alongside the per-test coverage files Bazel left behind. Naming a report is not enough on its own: in both the action and the orb, the named files are added to whatever the search turns up. You need the explicit name and search disabled.

Option 1: run the Codecov binary from the test task

The Codecov CLI is a downloaded binary, so install it first:

curl -Os https://cli.codecov.io/latest/linux/codecov   # or .../latest/macos/codecov
chmod +x codecov

aspect test --coverage \
  --coverage-tool=./codecov \
  --coverage-tool-arg=upload-process \
  --coverage-tool-arg=--disable-search \
  --coverage-tool-arg=-f \
  --coverage-tool-arg={report} \
  -- //...

Codecov reads its upload token from the CODECOV_TOKEN environment variable, so set it in the job environment rather than passing it as an argument. Both work, but the CLI echoes the coverage tool’s command line to the log before spawning it — a token passed as --coverage-tool-arg=-t ... ends up in your build output, where it’s only as protected as your provider’s log masking. The environment variable keeps it out entirely.

Buildkite
GitLab CI
CircleCI
GitHub Actions

.buildkite/pipeline.yaml

env:
  ASPECT_API_TOKEN: your-buildkite-secret-ref

steps:
  - key: test
    label: ":bazel: Test"
    command: |
      curl -fsSL https://install.aspect.build | bash
      curl -Os https://cli.codecov.io/latest/linux/codecov
      chmod +x codecov
      export CODECOV_TOKEN="$(buildkite-agent secret get CODECOV_TOKEN)"
      aspect test --task-key test \
        --coverage \
        --coverage-tool=./codecov \
        --coverage-tool-arg=upload-process \
        --coverage-tool-arg=--disable-search \
        --coverage-tool-arg=-f \
        --coverage-tool-arg={report} \
        -- //...

.gitlab-ci.yml

variables:
  ASPECT_API_TOKEN: $ASPECT_API_TOKEN  # masked CI/CD variable
  CODECOV_TOKEN: $CODECOV_TOKEN        # masked CI/CD variable

test:
  before_script:
    - curl -fsSL https://install.aspect.build | bash
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - curl -Os https://cli.codecov.io/latest/linux/codecov
    - chmod +x codecov
    - |
      aspect test --task-key test \
        --coverage \
        --coverage-tool=./codecov \
        --coverage-tool-arg=upload-process \
        --coverage-tool-arg=--disable-search \
        --coverage-tool-arg=-f \
        --coverage-tool-arg={report} \
        -- //...

.circleci/config.yml

version: 2.1

jobs:
  test:
    docker:
      - image: cimg/base:current
    # CODECOV_TOKEN comes from the `codecov` context attached in the workflow below.
    steps:
      - checkout
      - run: curl -fsSL https://install.aspect.build | bash
      - run: |
          curl -Os https://cli.codecov.io/latest/linux/codecov
          chmod +x codecov
      - run: |
          aspect test --task-key test \
            --coverage \
            --coverage-tool=./codecov \
            --coverage-tool-arg=upload-process \
            --coverage-tool-arg=--disable-search \
            --coverage-tool-arg=-f \
            --coverage-tool-arg={report} \
            -- //...

workflows:
  ci:
    jobs:
      - test:
          context: codecov

A context holding CODECOV_TOKEN is the usual way to expose it; a project environment variable works too.

.github/workflows/aspect.yaml

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    env:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@b1e9d142e86f63c10d603304daa22bf80492e24c # v2026.25.1
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - run: |
          curl -Os https://cli.codecov.io/latest/linux/codecov
          chmod +x codecov
      - run: |
          aspect test --task-key test \
            --coverage \
            --coverage-tool=./codecov \
            --coverage-tool-arg=upload-process \
            --coverage-tool-arg=--disable-search \
            --coverage-tool-arg=-f \
            --coverage-tool-arg={report} \
            -- //...

Option 2: use your platform’s Codecov integration

Write the report to a known path with --coverage-report, then let the platform’s own Codecov integration upload it. What that integration is — and whether one exists — varies by platform.

Buildkite
GitLab CI
CircleCI
GitHub Actions

Codecov publishes no official Buildkite plugin; their Buildkite guidance is to run an uploader in a command step, which is Option 1 above. Community plugins such as joscha/codecov wrap the same CLI if you’d rather express it as a plugin:

.buildkite/pipeline.yaml

steps:
  - key: test
    label: ":bazel: Test"
    command: aspect test --task-key test --coverage --coverage-report=coverage/lcov.dat -- //...
    plugins:
      - joscha/codecov#v4.0.2:
          args: ["upload-process", "--disable-search", "-f", "coverage/lcov.dat"]

Codecov does not support tokenless uploads from Buildkite, so CODECOV_TOKEN must be in the step environment either way.

Codecov ships no GitLab CI/CD component or template — their documented GitLab path is running the CLI binary, which is exactly Option 1 above.If you want the upload in a separate job anyway, hand the report over as an artifact and let the upload job run even when tests failed:

.gitlab-ci.yml

test:
  stage: CI
  script:
    - aspect test --task-key test --coverage --coverage-report=coverage/lcov.dat -- //...
  artifacts:
    when: always
    paths: [coverage/lcov.dat]

codecov:
  stage: CI
  needs: [test]
  when: always
  script:
    - curl -Os https://cli.codecov.io/latest/linux/codecov
    - chmod +x codecov
    - ./codecov upload-process --disable-search -f coverage/lcov.dat

The codecov/codecov orb provides a codecov/upload command:

.circleci/config.yml

version: 2.1

orbs:
  codecov: codecov/codecov@6.0.0

jobs:
  test:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - run: curl -fsSL https://install.aspect.build | bash
      - run: aspect test --task-key test --coverage --coverage-report=coverage/lcov.dat -- //...
      - codecov/upload:
          files: coverage/lcov.dat
          disable_search: true

workflows:
  ci:
    jobs:
      - test:
          context: codecov

The orb reads CODECOV_TOKEN from the environment by default, and its when parameter already defaults to always, so the upload runs even when the test step failed. Add fail_on_error: true if a rejected upload should fail the job.

codecov/codecov-action takes the report as an input:

.github/workflows/aspect.yaml

- run: aspect test --task-key test --coverage --coverage-report=coverage/lcov.dat -- //...

- uses: codecov/codecov-action@v5
  if: ${{ always() }}
  with:
    files: coverage/lcov.dat
    disable_search: true
    token: ${{ secrets.CODECOV_TOKEN }}

Unlike the CircleCI orb, the action does not run after a failed step on its own — if: ${{ always() }} is what keeps the upload happening when tests fail. Add fail_ci_if_error: true if a rejected upload should fail the job.

On Aspect Workflows CI runners aspect and bazel are pre-installed — drop the launcher install from these examples and keep the Codecov download.

​How this relates to bazel coverage

​Collecting coverage

​Publishing the report

​Codecov

​Option 1: run the Codecov binary from the test task

​Option 2: use your platform’s Codecov integration