Fix incorrect documentation about the token input to the Actions.

[chrisgavin]

This documentation is currently misleading as it implies you can use any token here. In reality, this Action calls API endpoints that only accept tokens from the GitHub Actions app, so you should basically never override it.

I believe all the other Actions in this repository will work with an arbitrary token if one needs to be provided for cross-repository access, but these two call the SARIF upload endpoint which requires an Actions token.

[aeisenberg]

I think security-events is required.

[aeisenberg]

I wonder if we should also include the guidance that it's best to avoid using this input and so the workflow falls back to using the actions-provided token.

[chrisgavin]

That might make sense, though I'm not sure how exactly to phrase it. There are some pretty specific situations where it is useful to be able to set these inputs, but in general they probably shouldn't be used.

[aeisenberg]

What do you think of this?

Most of the time it is advisable to avoid specifying this input so that the workflow falls back to using the default value.

If you need to specify the input, you will be an advanced user anyway, so I don't think this would be confusing.

[aeisenberg]

Nice.

[jsoref]

This is very confusing since the underlying api clearly says it's possible:
https://docs.github.com/en/rest/code-scanning/code-scanning?apiVersion=2022-11-28#upload-an-analysis-as-sarif-data--fine-grained-access-tokens

Oh well, at least the documentation now warns that this doesn't work.

I'd almost suggest that the description should say:

If you think you want to use a custom token you should probably talk to the endpoint directly instead of using this action.

• For analyze/action.yml that would mean with: { "upload": "never" } followed by a manual call to the endpoint.
• For upload-sarif/action.yml which is the one I actually use, I have no idea what to do since I'm pretty sure that the action is actually rewriting my sarif file with some extra hints, and I guess I'd need to find a way to ask code like that to do that rewrite and then manually call the endpoint directly.