Clarify what the "context" claim provides for OIDC tokens

[TomChapple]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect

What part(s) of the article would you like to see updated?

In this article, the concept of claim keys is introduced including how to specify them for an organisation and/or a repository. This is particularly helpful with the example OIDC token to relate what values would be available if a particular claim was requested.

However, the "context" claim (used in the default claim template) does not have a corresponding entry in the OIDC token. It makes sense that is doesn't, but it also leaves this claim as very ambiguous to its content and purpose, especially when it is excluded from the list of GitHub-provided claims.

Some sections refer to "context" and show how to use it along with some examples of its outputs listed in the "Example subject claims" (albeit without any mention of "context"). These examples do not show an obvious pattern in formatting, often leading me to questions such as "which order of 'ref' and 'environment' should I expect?". This uncertainty leads me towards explicitly specifying the individual claims instead of using the default, even if it could conceptually meet my requirements.

I understand that the "context" claim (from experimentation) changes its form depending on how the workflow was triggered. Although this might be inferred, there is no explicit answer to inform the user, reducing the confidence in using this claim.

I believe some description of the "context" claim as though it were a separate claim would be very beneficial. Given its dynamic state, details of what it includes and when it includes it would be very useful in determining whether the client requires additional claims. In the end, I want to be confident in knowing that this claim provides what I require.

Additional information

This was originally explored in Issue #22283, but was closed after addressing one of its other points on accessing the "repository" claim via "repo". Its other point regarding the ambiguity of "context" may not have been addressed.

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[nguyenalex836]

@TomChapple Thank you for raising this issue! I'll get this triaged for review ✨ Our team will provide feedback regarding the best next steps for this issue - thanks for your patience! 💛

[github-actions]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀