Improve token-id permission options

[rickstaa]

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 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 #25952.

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

[cmwilson21]

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

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.

[github-actions]

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

[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")

[github-actions]

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

[simonw]

This is still incredibly confusing.