Codecov Tokens

Codecov uses secret tokens to make sure the uploads we process for a project really come from that project. Tokens prevent fake or accidental uploads from making it into, for example, the main branch. A single bad upload to main affects the data we show for main itself as well as for pull requests that are based on main.

The way you configure a Codecov token is different depending on your CI provider, the type of token you're using, and the way you send uploads to Codecov.

When do I need a token?

For private repositories, all uploads require a token.

For public repositories, a token is required to send uploads to commits on protected branches. A protected branch corresponds to an actual branch in your repository (like main or master). An unprotected branch is any branch with a colon-separated prefix on it (like forkname:main or pr300:master).

The prefix for an unprotected branch name is something a CI job comes up with when it sends requests to Codecov and is not part of the repository or its branches.

Note: we have not yet taken down our legacy upload endpoint which is used in older Codecov configurations. This endpoint attempts to process tokenless uploads regardless of the branch name, but it is unreliable, unmaintained, and may be removed in the future.

Types of tokens

Repository tokens

Each repository has a unique Codecov token that will work for only that repository. Click the "Configure" button next to a repository in the Codecov UI or go to a repository's "Configuration" tab to view the token.

If a global upload token has been generated for the repository's owner, it will be shown on this screen instead of a per-repository token. The per-repository token can still be viewed in the repository's "Configuration" tab in the "General" section.

Global upload tokens

Account owners or organization administrators can create a single global upload token which will work for all of the repositories owned by the account or organization. Setting a global upload token as an organization-wide secret in CI settings makes it easier to set up Codecov for new repositories.

Create one in the account or organization's settings page in the Codecov UI:

If an account or organization has a global upload token, the Codecov UI will display it instead of a repository token for every repository belonging to the account or organization.

Self-hosted upload tokens

Self-hosted Codecov installations can define a token in their installation YAML. Learn more in the documentation for self-hosting Codecov.

Using your token

Once you have your token, there are two steps needed to set it up:

• In your CI provider's settings, create a secret CODECOV_TOKEN variable and set its value to your token's value
• In your CI job definition, pass the value of the CODECOV_TOKEN variable to the Codecov CLI / uploader

The details of these steps differ depending on your CI provider and how you send uploads to Codecov.

Example: GitHub Actions + Official Codecov Action

Official GitHub Actions documentation: Using secrets in GitHub Actions and Storing credentials for Dependabot to use.

If you are are using a global upload token and have the necessary permissions, open the "Settings" page for your organization on GitHub.

Otherwise, open the "Settings" page for your repository (as shown below). Expand the "Secrets and variables" section and select "Actions". Click the "New repository secret" button.

Create a new repository secret called CODECOV_TOKEN. Set its value to your Codecov token. Make sure not to include anything other than the token; for example, don't include anything like CODECOV_TOKEN=.

Next, update your GitHub Actions testing workflow so that it runs the official Codecov action.

steps:
- uses: codecov/codecov-action@v4
  with:
    token: ${{ secrets.CODECOV_TOKEN }}

And that's it. Uploads from private GitHub repos, or protected branches on public repos, now happen with a token.

Uploading without a token

Codecov does not require a token for an upload when both the following conditions are true:

• the repository is public
• the upload is for a commit that is on an unprotected branch (like forkname:main)

Projects that accept contributions from forks can add a prefix to the contribution's branch name and send uploads to Codecov without having to expose any CI secrets.

Maintainers who don't have administrator permissions for their projects can partially work around the token requirement by adding : to every branch name.

Using the latest Codecov GitHub Action

The latest version of the Codecov GitHub Action automatically modifies the branch name when a token isn't available. Codecov should work smoothly on pull requests from forks out of the box.

Using the Codecov CLI or other CI providers

If you're using the official CI action for another CI provider, or your CI jobs use the Codecov CLI directly, your CI jobs will need to come up with an unprotected branch name on their own. This could be based on the PR number, the username of the fork's author, or something else.

Legacy upload methods

🚧

Tokenless uploads from legacy uploaders are unreliable

Tokenless uploads from legacy uploaders, or from CI actions that wrap them, share a global, Codecov-wide rate limit imposed by CI services. When this rate limit is exceeded, uploads fail and Codecov won't post CI statuses or PR comments.

Please update to the latest versions of our CI actions or the Codecov CLI for more reliable tokenless uploads.

Codecov's legacy uploaders and older versions of our pre-made CI actions use a legacy upload endpoint with different authentication requirements. This legacy endpoint attempts to accept all tokenless uploads, regardless of the branch name, for public projects that use certain CI providers (Travis-CI, CircleCI, Azure, GitHub Actions).

This legacy endpoint is unreliable, unmaintained, and may be removed in the future. Please upgrade to the latest version of the Codecov CLI or the pre-made CI action for your CI provider.