Codecov GitHub Action

Easily upload coverage reports to Codecov from GitHub Actions

v5 Release

v5 of the Codecov GitHub Action will use the Codecov Wrapper to encapsulate the CLI. This will help ensure that the Action gets updates quicker.

Migration Guide

The v5 release also coincides with the opt-out feature for tokens for public repositories. In the Global Upload Token section of the settings page of an organization in codecov.io, you can set the ability for Codecov to receive a coverage reports from any source. This will allow contributors or other members of a repository to upload without needing access to the Codecov token. For more details see how to upload without a token.

[!WARNING] The following arguments have been changed

• file (this has been deprecated in favor of files)
• plugin (this has been deprecated in favor of plugins)

The following arguments have been added:

• binary
• gcov_args
• gcov_executable
• gcov_ignore
• gcov_include
• report_type
• skip_validation
• swift_project

You can see their usage in the action.yml file.

v4 Release

v4 of the Codecov GitHub Action will use the Codecov CLI to upload coverage reports to Codecov.

Breaking Changes

• Tokenless uploading is unsupported. However, PRs made from forks to the upstream public repos will support tokenless (e.g. contributors to OSS projects do not need the upstream repo's Codecov token). For details, see our docs
• Various arguments to the Action have been removed

Dependabot

• For repositories using Dependabot, users will need to ensure that it has access to the Codecov token for PRs from Dependabot to upload coverage. To do this, please add your CODECOV_TOKEN as a Dependabot Secret. For more information, see "Configuring access to private registries for Dependabot."

v3 versions and below will not have access to CLI features (e.g. global upload token, ATS).

Usage

To integrate Codecov with your Actions pipeline, specify the name of this repository with a tag number (@v5 is recommended) as a step within your workflow.yml file.

This Action also requires you to provide an upload token from codecov.io (tip: in order to avoid exposing your token, store it as a secret).

Currently, the Action will identify linux, macos, and windows runners. However, the Action may misidentify other architectures. The OS can be specified as

• alpine
• alpine-arm64
• linux
• linux-arm64
• macos
• windows

Inside your .github/workflows/workflow.yml file:

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)

The Codecov token can also be passed in via environment variables:

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
    verbose: true # optional (default = false)
  env:
    CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

[!NOTE] This assumes that you've set your Codecov token inside Settings > Secrets as CODECOV_TOKEN. If not, you can get an upload token for your specific repo on codecov.io. Keep in mind that secrets are not available to forks of repositories.

Using OIDC

For users with OpenID Connect(OIDC) enabled, the Codecov token is not necessary. You can use OIDC with the use_oidc argument as following.

- uses: codecov/codecov-action@v5
  with:
    use_oidc: true

Any token supplied will be ignored, as Codecov will default to the OIDC token for verification.

Arguments

Codecov's Action supports inputs from the user. These inputs, along with their descriptions and usage contexts, are listed in the table below:

tional | flags | Comma-separated list of flags to upload to group coverage metrics. | 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 | 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 "testing", "coverage". | Optional | root_dir | Root folder from which to consider paths on the network section. Defaults to current working directory. | 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 | verbose | Enable verbose logging | Optional | version | Which version of the Codecov CLI to use (defaults to 'latest') | Optional | working-directory | Directory in which to execute codecov.sh | Optional

Example workflow.yml with Codecov Action

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

Contributing

Contributions are welcome! Check out the Contribution Guide.

License

The code in this project is released under the MIT License.