Clarify what the "context" claim provides for OIDC tokens #34572
Labels
actions
This issue or pull request should be reviewed by the docs actions team
content
This issue or pull request belongs to the Docs Content team
needs SME
This proposal needs review from a subject matter expert
waiting for review
Issue/PR is waiting for a writer's review
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.
The text was updated successfully, but these errors were encountered: