Codecov GitHub Action

To upload coverage reports to Codecov, add the codecov/codecov-action@v5 step to your GitHub Actions workflow.

Prerequisites:

• You must run actions/checkout before the Codecov step.
• Your runner must have bash, curl, git, and gpg installed (standard on GitHub-hosted runners, but required for custom runners/containers).
• You must provide a Codecov upload token, which should be stored as a GitHub Secret (e.g., CODECOV_TOKEN).

Note on Forks: Secrets are not available to forks of repositories. However, for public repositories, contributors to forks can upload coverage without a token if the organization has enabled the 'Global Upload Token' feature in Codecov settings.

steps:
  - uses: actions/checkout@main
  - uses: codecov/codecov-action@v5
    with:
      fail_ci_if_error: true # optional (default = false)
      files: ./coverage1.xml,./coverage2.xml # optional
      flags: unittests # optional
      name: codecov-umbrella # optional
      token: ${{ secrets.CODECOV_TOKEN }}
      verbose: true # optional (default = false)

To upload coverage reports to Codecov from a GitHub Actions workflow, use the codecov/codecov-action action. You can specify the directory containing reports, add metadata via env_vars or flags, and provide your repository token via the token input.

Commonly used inputs include:

• directory: The folder to search for coverage files (defaults to current working directory).
• files: A comma-separated list of explicit files to upload. Use !path to exclude files.
• flags: A comma-separated list of flags to group coverage metrics.
• token: Your repository Codecov token.
• fail_ci_if_error: If set to true, the action will exit with a non-zero code on error.

name: Example workflow for Codecov
on: [push]
jobs:
  run:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    env:
      OS: ${{ matrix.os }}
      PYTHON: "3.10"
    steps:
      - uses: actions/checkout@main
      - name: Setup Python
        uses: actions/setup-python@main
        with:
          python-version: "3.10"
      - name: Generate coverage report
        run: |
          pip install pytest
          pip install pytest-cov
          pytest --cov=./ --cov-report=xml
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v5
        with:
          directory: ./coverage/reports/
          env_vars: OS,PYTHON
          fail_ci_if_error: true
          files: ./coverage1.xml,./coverage2.xml,!./cache
          flags: unittests
          name: codecov-umbrella
          token: ${{ secrets.CODECOV_TOKEN }}
          verbose: true

The following table lists the available inputs for the Codecov GitHub Action. Most inputs are optional.

| Input  | Description | Required |
| :---       | :---     | :---:   |
| `base_sha` | 'The base SHA to select. This is only used in the "pr-base-picking" run command' | Optional |
| `binary` | The file location of a pre-downloaded version of the CLI. If specified, integrity checking will be bypassed. | Optional |
| `codecov_yml_path` | The location of the codecov.yml file. This is currently ONLY used for automated test selection (https://docs.codecov.com/docs/getting-started-with-ats). Note that for all other cases, the Codecov yaml will need to be located as described here: https://docs.codecov.com/docs/codecov-yaml#can-i-name-the-file-codecovyml | Optional |
| `commit_parent` | SHA (with 40 chars) of what should be the parent of this commit. | Optional |
| `directory` | Folder to search for coverage files. Default to the current working directory | Optional |
| `disable_file_fixes` | Disable file fixes to ignore common lines from coverage (e.g. blank lines or empty brackets). Read more here https://docs.codecov.com/docs/fixing-reports | Optional |
| `disable_search` | Disable search for coverage files. This is helpful when specifying what files you want to upload with the files option. | Optional |
| `disable_safe_directory` | Disable setting safe directory. Set to true to disable. | Optional |
| `disable_telem` | Disable sending telemetry data to Codecov. Set to true to disable. | Optional |
| `dry_run` | Don't upload files to Codecov | Optional |
| `env_vars` | Environment variables to tag the upload with (e.g. PYTHON | OS,PYTHON) | Optional |
| `exclude` | Comma-separated list of folders to exclude from search. | Optional |
| `fail_ci_if_error` | On error, exit with non-zero code | Optional |
| `files` | Comma-separated explicit list of files to upload. These will be added to the coverage files found for upload. If you wish to only upload the specified files, please consider using "disable_search" to disable uploading other files. | Optional |
| `flags` | Comma-separated list of flags to upload to group coverage metrics. | Optional |
| `force` | Only used for empty-upload run command | Optional |
| `git_service` | Override the git_service (e.g. github_enterprise) | Optional |
| `gcov_args` | Extra arguments to pass to gcov | Optional |
| `gcov_executable` | gcov executable to run. Defaults to 'gcov' | Optional |
| `gcov_ignore` | Paths to ignore during gcov gathering | Optional |
| `gcov_include` | Paths to include during gcov gathering | Optional |
| `handle_no_reports_found` | If no coverage reports are found, do not raise an exception. | Optional |
| `job_code` |  | Optional |
| `name` | Custom defined name of the upload. Visible in the Codecov UI | Optional |
| `network_filter` | Specify a filter on the files listed in the network section of the Codecov report. This will only add files whose path begin with the specified filter. Useful for upload-specific path fixing. | Optional |
| `network_prefix` | Specify a prefix on files listed in the network section of the Codecov report. Useful to help resolve path fixing. | Optional |
| `os` | Override the assumed OS. Options available at cli.codecov.io | Optional |
| `override_branch` | Specify the branch to be displayed with this commit on Codecov | Optional |
| `override_build` | Specify the build number manually | Optional |
| `override_build_url` | The URL of the build where this is running | Optional |
| `override_commit` | Commit SHA (with 40 chars) | Optional |
| `override_pr` | Specify the pull request number manually. Used to override pre-existing CI environment variables. | Optional |
| `plugins` | Comma-separated list of plugins to run. Specify `noop` to turn off all plugins | Optional |
| `recurse_submodules` | Whether to enumerate files inside of submodules for path-fixing purposes. Off by default. | Optional |
| `report_code` | The code of the report if using local upload. If unsure, leave unset. Read more here https://docs.codecov.com/docs/the-codecov-cli#how-to-use-local-upload | Optional |
| `report_type` | The type of file to upload, coverage by default. Possible values are "test_results", "coverage". | Optional |
| `root_dir` | Root folder from which to consider paths on the network section. Defaults to current working directory. | Optional |
| `run_command` | Choose which CLI command to run. Options are "upload-coverage", "empty-upload", "pr-base-picking", "send-notifications". "upload-coverage" is run by default. | Optional |
| `skip_validation` | Skip integrity checking of the CLI. This is NOT recommended. | Optional |
| `slug` | [Required when using the org token] Set to the owner/repo slug used instead of the private repo token. Only applicable to some Enterprise users. | Optional |
| `swift_project` | Specify the swift project name. Useful for optimization. | Optional |
| `token` | Repository Codecov token. Used to authorize report uploads | Optional |
| `url` | Set to the Codecov instance URl. Used by Dedicated Enterprise Cloud customers. | Optional |
| `use_legacy_upload_endpoint` | Use the legacy upload endpoint. | Optional |
| `use_oidc` | Use OIDC instead of token. This will ignore any token supplied | Optional |
| `use_pypi` | Use the pypi version of the CLI instead of from cli.codecov.io. If specified, integrity checking will be bypassed. | Optional |
| `verbose` | Enable verbose logging | Optional |
| `version` | Which version of the Codecov CLI to use (defaults to 'latest', must start with a leading 'v'; example: `v10.0.1`) | Optional |
| `working-directory` | Directory in which to execute codecov.sh | Optional |

The following arguments are available for configuring the codecov/codecov-action: