Enhancement: List what permissions the GitHub PAT requires

[Rarefy-Dev]

My GitHub PAT is not working when I use it with this dashboard. Looking at the even log for cpuad-updater, this tool runs these APIs I think this is what is required. If you can confirm, I will make a pull request to the README.MD to add it to the documentation.

GitHub URLs and Permissions Needed:

replace ORG with your organization
https://api.github.com/orgs/ORG/teams?page=1&per_page=50
https://api.github.com/orgs/ORG/copilot/billing
https://api.github.com/orgs/ORG/copilot/billing/seats?page=1&per_page=50
https://api.github.com/orgs/ORG/copilot/metrics

For full read-only access to GitHub data for reporting, you will need to set the following permissions for your GitHub token:

• read:org
• read:repo:status
• read:repo_deployment
• read:public_repo
• read:user
• read:discussion
• read:packages
• read:project

[satomic]

hi @Rarefy-Dev thank you for you feedback

1. Did it works now after you add full read-only permissions? If it still doesn't, what error message is displayed?
2. In addition, I am sure that only these three permissions manage_billing:copilot, read:enterprise, read:org need to be set for token (classic) to allow cpuad-updater to retrieve data normally.
3. There are two possible reasons why tokens cannot work properly, can you check these two settings please:
   a. You need to authorize SSO for the token, which can be seen on the token page.
   
   b. You also need to set the organization to allow token access.
   

[Rarefy-Dev]

Thank you. We have a token that works for curl now. We are using an enterprise version of github. These api calls work in command line

curl -L --ssl-no-revoke  -H "Accept: application/vnd.github+json" -H "Authorization: Bearer OurNewToken" -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/enterprises/OurEnt/teams
curl -L --ssl-no-revoke  -H "Accept: application/vnd.github+json" -H "Authorization: Bearer OurNewToken" -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/enterprises/OurEnt/copilot/metrics
curl -L --ssl-no-revoke  -H "Accept: application/vnd.github+json" -H "Authorization: Bearer OurNewToken" -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/enterprises/OurEnt/copilot/billing/seats

I noticed from the cpuad-updater log that its making calls to:
Requesting URL: https://api.github.com/orgs/OurEnt/copilot/billing/seats?page=1&per_page=50

Do I need to make a config change to have it hit the enterprise end points?

Thanks for your help,
Mark

[satomic]

Hi @Rarefy-Dev Thanks for your feedback, and this project is designed to "not directly support Enterprise endpoints"

The reason is: many Enterprise administrators will not enable Copilot for all Organizations in the Enterprise, and most of the scenarios that care about Copilot usage and want to check are performed by the Organization Owner.

Instead, if you are an Enterprise administrator and you want to view Copilot usage in the entire Enterprise, you can specify multiple Organizations through the ORGANIZATION_SLUGS environment variable when starting the cpuad-updater service. For details, please refer to here. So you need to manually point out which Organizations in your Enterprise need to be visualized. For example:

docker run -itd \
--net=host \
--restart=always \
--name cpuad \
-e GITHUB_PAT="<YOUR_GITHUB_PAT>" \
-e ORGANIZATION_SLUGS="myOrg1,myOrg2,myOrg3,myOrg4....,myOrgN" \
-e LOG_PATH="logs" \
-e EXECUTION_INTERVAL=1 \
-e ELASTICSEARCH_URL="http://localhost:9200" \
-e TZ="GMT" \ # change to your local timezone if needed
-v /srv/cpuad-updater-logs:/app/logs \
satomic/cpuad-updater

In addition, the cpuad-updater service supports running multiple instances at the same time, so even if you have multiple Enterprises that need to be presented to the same Grafana Dashboard, there is no problem. You can refer to the discussion in this issue.

[l3ender]

A note for others: you could also run into PAT issues if your enterprise has IP whitelists enabled and the application is running in an environment whose IP address(es) are not whitelisted.