From 026e675dcfb547de46e22ba67f33be1b175f5725 Mon Sep 17 00:00:00 2001 From: chris48s <chris48s@users.noreply.github.com> Date: Mon, 23 Jan 2023 19:46:19 +0000 Subject: [PATCH] add a note about fine-grained PATs in the docs (#8823) Co-authored-by: repo-ranger[bot] <39074581+repo-ranger[bot]@users.noreply.github.com> --- doc/server-secrets.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/server-secrets.md b/doc/server-secrets.md index 1270e9079e..ebecef355a 100644 --- a/doc/server-secrets.md +++ b/doc/server-secrets.md @@ -125,11 +125,17 @@ Because of GitHub rate limits, you will need to provide a token, or else badges will stop working once you hit 60 requests per hour, the [unauthenticated rate limit][github rate limit]. -You can [create a personal access token][personal access tokens] through the +You can [create a personal access token][personal access tokens] (PATs) through the GitHub website. When you create the token, you can choose to give read access to your repositories. If you do that, your self-hosted Shields installation will have access to your private repositories. +For most users we recommend using a classic PAT as opposed to a [fine-grained PAT][fine-grained pat]. +It is possible to request a fairly large subset of the GitHub badge suite using a +fine-grained PAT for authentication but there are also some badges that won't work. +This is because some of our badges make use of GitHub's v4 GraphQL API and the +GraphQL API only supports authentication with a classic PAT. + When a `gh_token` is specified, it is used in place of the Shields token rotation logic. @@ -139,6 +145,7 @@ token, though it's not required. [github rate limit]: https://developer.github.com/v3/#rate-limiting [personal access tokens]: https://github.com/settings/tokens +[fine-grained pat]: https://github.blog/2022-10-18-introducing-fine-grained-personal-access-tokens-for-github/ - `GH_CLIENT_ID` (yml: `private.gh_client_id`) - `GH_CLIENT_SECRET` (yml: `private.gh_client_secret`) -- GitLab