Document permission requirements for private repositories

[trymzet]

For private repos, due to this undocumented behavior of GitHub actions, it seems an additional contents: read permission is required for the action:

permissions:
  id-token: write # IMPORTANT: this permission is mandatory for trusted publishing.
  contents: read

Otherwise, the action fails while trying to fetch the repo:

remote: Repository not found.
Error: fatal: repository 'https://github.com/my-org/my-repo' not found
The process '/usr/bin/git' failed with exit code 128

NOTE: I tested this with a repo using Trusted Publishing.

[woodruffw]

I can confirm that I've seen the same behavior. I think this may depend on the parent GH user/org/enterprise's default GHA token permissions, but either way it's likely to be a common snare when people publish from a private repo.

[webknjaz]

@trymzet thanks for letting us know, I didn't realize. I'd love to get contributions updating the snippets @ https://github.com/pypa/gh-action-pypi-publish/blob/unstable/v1/README.md and https://github.com/pypa/packaging.python.org/blob/main/source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml with that privilege and a similar code comment explaining why it's needed.