Suggested improvements to explanation of id-token: write

[simonw]

Code of Conduct

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

What article on docs.github.com is affected?

The explanation of what id-token: read/write/none means in a GitHub Actions workflow is still really confusing. Previous issues about this include:

• https://github.com/github/docs/issues/14626
• https://github.com/github/docs/issues/25952
• https://github.com/github/docs/issues/26481

I guess the most relevant article is this one: https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#adding-permissions-settings

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

Here's my understanding of this feature. Feel free to use any of this copy, or correct me if I got something wrong!

---

The id-token: write permission provides a workflow the ability to interact with external services that use OpenID Connect (OIDC).

The write value can be better interpreted as meaning "enabled" - no writes occur with this permission, and it does not imply that the workflow has the ability to write to anything within GitHub.

Instead, this permission allows the workflow to request an access token from an OIDC supporting external service, such as PyPI or AWS or Google Cloud.

When the GitHub Action workflow runs it will request a token from the relevant service. That service will be able to identify the workflow and repository that is making the request and will only return a token for workflows that it has been configured to allow.

A value of id-token: read is treated the same as id-token: none (the default) - workflows without id-token: write will be unable to request tokens from external services using OIDC.

Additional information

No response

[simonw]

The table on this page also mentions id-token, and references read permissions: https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token

I don't understand the relevance of read here.

[nguyenalex836]

@simonw Thank you for opening this issue! I'll get this triaged for review ✨

[github-actions[bot]]

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

[nguyenalex836]

@simonw Hello! 👋 Thank you for your patience while our team reviewed this issue! After discussing this issue with our technical writing team, we are going to loop in one of our Actions SMEs, given the complexity of this topic.

We'll provide another update once the Actions SME has reviewed 💛

[nguyenalex836]

@simonw Hi again! 👋 Thank you again for your patience while our Actions SME team reviewed. They wanted to ensure you had a chance to view this portion of the documentation regarding permissioning, and wanted to offer some additional context -

For reusable workflows outside the org and also for pull requests from public forked repos , default value issued to id-token is "read" to be safe and restrictive. Users could change it to "write" if they want to explicitly grant permissions for the workflow to request an OIDC JWT.

Does this help clarify some of the confusion regarding id-token: read/write/none?

[github-actions[bot]]

This issue has been automatically closed because there has been no response to our request for more information from the original author. With only the information that is currently in the issue, we don't have enough information to take action. Please reach out if you have or find the answers we need so that we can investigate further. See this blog post on bug reports and the importance of repro steps for more information about the kind of information that may be helpful.

[danielcompton]

@nguyenalex836 I can't speak for @simonw but for me that doesn't really make sense, or at least doesn't fully explain what id-token: read means.

[nguyenalex836]

@danielcompton Thank you for letting me know! 💛 Would you be open to raising a new, separate issue that includes the specific points that you are looking for clarity on regarding id-token: read?

[janbrasna]

I don't think this topic needs a new issue every single time a stale bot closes out the previous one;) I'm afraid it needs a better documentation explaining what the actual permission setting is and what it is for (not the whole OIDC workflow, that one clearly states when you need the permission, own-org vs. outside-org reusables etc. — but what the actual values for that permission mean, and if/when/how they can be set). Ex without the great writeup about OIDC use for deploy-pages I could have only guessed why such permission is necessary to grant, without any more explanation than to just blindly follow the boilerplate.

(In case of deploy-pages, the token here contains more info about the source event/repo protections wrt the environment to be deployed to, in a standardized way, that's not implicit on GITHUB_TOKEN, and GH apparently chose to consume their own OIDC mechanism instead of getting that info via GH API using the default token scope I guess…)

Connecting to cloud providers like AWS or GCP is pretty well documented here, but the issues cropping up repeatedly are about the lack of documentation for:

1. why GH itself needs the permission (and OIDC flow to start with) for Pages deployment (only mentioned by the authors above),
2. what does the "read" permission really mean, and why it can't be set, even though it's supposedly a valid value being used by default in some scenarios (and if that's a maximum permission for PRs from forks, what that means in real life, compared to "none").

I see it being rather unpopular topic with how often it ends up closed out by stale bot, but perhaps it's too obvious for engineers architecting the functionality, but without any visibility into how that values are then used for what in GHA code, we the end users are then left in the dark to just blindly trust the actions' instructions, or keep running in circles between unresolved issues trying to asses the potential impact this setting could have if not used correctly.

But if you really want, there's another confused consumer:

• #33483 ;D

[nguyenalex836]

@janbrasna Thank you for the incredibly thoughtful comment! This is certainly a nuanced topic, but just to get us all on the same page, the next development / response on the id-token: front will be documented on the issue you linked above once our team has had a chance to discuss this further 💛 https://github.com/github/docs/issues/33483