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, so we encourage organizations to require tokens for all uploads.

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 if your organization has disabled tokenless uploads for public repositories.

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 admin 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 GitHub repos now happen with a token.

Uploading without a token

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

• the repository is public and the organization has enabled tokenless uploads for public repositories

or

• the repository is public and is not on a "protected" branch

Enabling Tokenless Uploads for Public Repositories

Available on >v5.0 of the codecov-action or v>0.9 of the codecov-cli

This setting is only visible to admin users, and you must be an admin to change this setting. Codecov inherits admin status from your git provider; an admin on your git provider is also an admin on Codecov.

Existing organizations will have tokens Required by default, but new organizations will start with tokens Not required. The setting is on the Global Upload Token tab of the Settings page.

If you wish to do a tokenless upload, there is no need to generate or set any tokens or secrets on your project or your workflow. You can still send in a token, but if the request qualifies as a tokenless upload, the token sent with your request will not be checked.

Tokenless on Unprotected Branches

A protected branch corresponds to a permanent 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).

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.

Starting on >v4.0 of the codecov-action, the branch name on pull requests from forks is automatically modified to include a :. Codecov should work smoothly on pull requests from forks out of the box.

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.