Provide more details on permissions needed by `scriv github-release`

[ncoghlan]

With fine-grained access tokens available on GitHub, it would be helpful to be more explicit about the permissions needed by scriv github-release.

From reading the code, I believe it is just the "Contents: write" permissions needed to access the following endpoints:

• https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#create-a-release
• https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#update-a-release

I'm not sure how best to word that in the docs, though (otherwise this would have been a PR instead of a docs issue report)

[nedbat]

Hmm, the docs seem to indicate that a fine-grained token with Contents:write would be enough, but an empirical test gave me 404 errors. I also tried Contents:write and Workflows:write, and had the same result.

If anyone has clearer information, let me know!

[ncoghlan]

I'll be doing a new venvstacks release soon, so I'll invest some time in seeing if I can get this running in a workflow.

[ncoghlan]

A 404 error here as well: https://github.com/lmstudio-ai/venvstacks/actions/runs/14387910093/job/40347735332

The supposedly failing URL works if I click on it in the action log:

• https://api.github.com/repos/lmstudio-ai/venvstacks/releases

[ncoghlan]

Missing piece was to pass the workflow token through to the runtime environment so scriv can access it: lmstudio-ai/venvstacks@ce9ecd3

I have https://github.com/lmstudio-ai/venvstacks/blob/main/.github/workflows/prepare-release.yml set up on a manual trigger, but it would be straightforward to tweak that to trigger on pushed tags instead.

[ncoghlan]

Huh, it turns out doing it that way doesn't trigger the release job that publishes to PyPI: https://stackoverflow.com/questions/69063452/github-actions-on-release-created-workflow-trigger-not-working

Edit: while the implicit trigger won't fire, I expect that explicitly invoking the publication workflow from the release definition one will work.

[ncoghlan]

My conclusion from my experiment:

• contents: write is the only required permission
• GITHUB_TOKEN needs to be passed in to the step environment
• if the default job token is used, release-triggered workflows won't run unless the release creation workflow explicitly invokes them