Documentation of tokenless upload feature is no longer available

[per1234]

The action has a very significant feature of supporting tokenless coverage data uploads for pull requests from forks. This is quite a complex subject because it relates to the frequently misunderstood behavior of workflow access to repository secrets in pull requests. Reports for pull requests from external contributors is one of the most valuable features of Codecov. So it is essential that this tokenless upload feature be clearly documented.

The action's documentation of the feature only mentions it in passing, pointing the reader to the documentation on the Codecov website:

https://github.com/codecov/codecov-action/blob/943cea186cc641c4ac8f55492baec4c2654291b4/README.md#breaking-changes

Breaking Changes

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

And the same approach is used by the maintainers when responding to various user reports and inquiries about upload tokens. For example, from #1293 (comment):

except for when uploading from forks as detailed here

Unfortunately, for some unknown reason, Codecov has since removed this important information from the documentation (seems to have happened around 2024-07-26 because I can see it on the 2024-07-25 archive of the page, but not on the the 2024-07-26 archive). So these links don't actually lead to any information about the feature and there is no detailed information about the feature available anywhere in the action's documentation or on the Codecov website.

Please restore that part of the Codecov documentation, or if that is not possible, add the information in this repository's documentation. The removed documentation content can be recovered from this Wayback Machine archive of the page from before it was removed, but make sure to review it in case it has become outdated since the time it was written:

https://web.archive.org/web/20240725044352/https://docs.codecov.com/docs/codecov-uploader#supporting-token-less-uploads-for-forks-of-open-source-repos-using-codecov

Supporting Token-less Uploads for forks of Open Source Repos using Codecov

As you can see, all examples show uploading to Codecov with the Codecov Token (or the org level Global Upload Token). However, forks of open source Github repositories do not have access to secrets from the upstream repo (without some clever configuration). This is why the Codecov CLI starting with v0.7.1 (and the Codecov Action starting with v4.0.0) support token-less uploads.

---

🚧 IMPORTANT: Currently there are constraints for token-less uploading

The rules for token-less uploading are:

1. You are uploading to a public repository
2. The branch of the commit you are targeting contains a ":", for example: username:branch_name

The reasoning for this is that we don't want unauthenticated users to be able to overwrite coverage on branches that belong to the upstream repository. So we protect those branches from token-less uploads.

The reasoning for the ":" character being required in the branch supplied to Codecov is that it's a restricted character in Git and is often used to delimit the name of the owner of a fork and the branch name in a PR. The restricted character part is important because this leaves no chance for an unauthenticated uploader to overwrite the coverage of a branch that belongs to the upstream repository.

---

And I note this is significantly different from the information provided by a previous version.

Related

• Provide clarity on future of tokenless uploads from GitHub Actions #1293