Suggested improvements to explanation of id-token: write

[simonw]

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?

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

• Document id-token permission #14626
• Document id-token permission #25952
• Improve token-id permission options #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]

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

[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?