Improve `token-id` permission options

[rickstaa]

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 options that can be used for the token-id permission are not documented. The documentation states that this key can take on the following values:

• write: Allows a JWT token to be requested from GitHub's OIDC provider and (temporarily) written to the GitHub backend.
• read: This option is unclear and looks deprecated.
• none: Functions similarly to the (deprecated) read option.

However, when setting the token-id to read, a github action fails with an Unexpected value 'read' error. When the write or none options are used, the workflow has no error. It, therefore, looks as if:

1. The read option was deprecated, but the documentation is not yet updated.
2. The github action runner has a bug.

Since I don't know which of these two is correct, I did not yet create a PR to fix the documentation but decided to wait for the @github team to clarify this.

How to reproduce

To see this problem in action, go to this example repository and check the latest action runs:

• ✔️ id-token: write (works).
• ❌ id-token: read (fails).
• ✔️ id-token: none (works).

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

1. The options given for the id-token key in https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs#overview should be updated from:

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  id-token: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

to

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  id-token: write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

4. The read option should also be removed from https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#adding-permissions-settings.

Additional information

This issue is related but slightly different than https://github.com/github/docs/issues/25952.

[welcome[bot]]

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.

[cmwilson21]

@rickstaa Thanks so much for opening an issue! I'll triage this for the team to take a look :eyes:

And welcome to the community! 🎉

While this is awaiting review, help wanted section if you are looking for other ways to contribute. ✨

[cmwilson21]

@rickstaa Also, if this is blocking you, please reach out to our awesome support team for additional help.

And thanks again for the issue and for so clearly defining your problem 💖

[rickstaa]

• ✔️ id-token: none (works).

@cmwilson21, thanks for your quick response. Take your time; it's not blocking since people can set token-id to none as a workaround 👍🏻.

[evankanderson]

FWIW, I had the same question today. I'm assuming the write value was chosen because it allows requesting a token which can be used to authenticate to other services (and possibly call arbitrary protected methods), but there doesn't seem to be a clear place that explains what this permission is.

[Codeup357]

Well done

[Adeyo9670]

Send funds to my newly created wallet$1,000,000.00

[Adeyo9670]

Brandy calls home at 10:30pm tonight and forgets why she called

[github-actions[bot]]

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

[faubion-hbo]

there is also a reference to seeing id-token to read under this heading: https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token (as value for "Maximum access for pull requests from public forked repositories")

[Qerenfil]

maintainer removed spammy comment

[Qerenfil]

maintainer removed spammy comment

[github-actions[bot]]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[simonw]

This is still incredibly confusing.

[janbrasna]

Super confusing;)

@rickstaa To quote from another thread:

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?

Originally posted by @nguyenalex836 in https://github.com/github/docs/issues/32320#issuecomment-2065295887

So for me that means, that the id-token can in some scenarios be "read" by default, but can't be explicitly set to that value by the action author(?).

(But with completely basic docs on what the id-token values really mean missing, I can't really make the mental model of what "read" and "to be safe and restrictive" really means in the context, how that differs from "none", probably without seeing some internals of how that is being used in the runners I won't be able to wrap my head around how that works and unfortunately just keep cargo-culting their use as directed by the actions' authors;)…)