Add a suggestive log for GitHub API rate-limiting issue during install

[3V3RYONE]

west sdk install may fail with a GitHub API rate-limit (HTTP 403) error. This typically occurs when the command is run multiple times after previous failures, which is common for new users setting up the project. Currently, the thrown exception only links to a generic GitHub rate-limit documentation page, which may be confusing to users.

Users can bypass the rate limit by authenticating with GitHub using a Personal Access Token. The install script supports this via the --personal-access-token argument. Therefore, detect rate-limit related failures and print a helpful message suggesting the use of this argument.

Fixes #93693

[github-actions]

Hello @3V3RYONE, and thank you very much for your first pull request to the Zephyr project!
Our Continuous Integration pipeline will execute a series of checks on your Pull Request commit messages and code, and you are expected to address any failures by updating the PR. Please take a look at our commit message guidelines to find out how to format your commit messages, and at our contribution workflow to understand how to update your Pull Request. If you haven't already, please make sure to review the project's Contributor Expectations and update (by amending and force-pushing the commits) your pull request if necessary.
If you are stuck or need help please join us on Discord and ask your question there. Additionally, you can escalate the review when applicable. 😊

[pdgendt]

Please fix the compliance issue (git commit subject too long)

[marc-hb]

--personal-access-token is long and inconvenient, could you test .netrc and add it as a recommendation in the --help if it works?
https://docs.python-requests.org/en/latest/user/authentication/#netrc-authentication

If someone has a valid access token, why would they store it in the wrong place and use it only with west sdk --personal-access-token ...? Weird. There are many other ways to hit rate limits.

[pdgendt]

--personal-access-token is long and inconvenient, could you test .netrc and add it as a recommendation in the --help if it works? docs.python-requests.org/en/latest/user/authentication#netrc-authentication

It's an argument for the west sdk extension.

[marc-hb]

It's an argument for the west sdk extension.

And? I miss your point sorry.

[pdgendt]

And? I miss your point sorry.

Why shouldn't we refer to an option that is available for the same command that the user just tried to execute?

[marc-hb]

I didn't say --personal-access-token should not be referred to. I only said that (if it works) the most common .netrc option that is much better for most people and/or use cases should not be missing.

[3V3RYONE]

@marc-hb @pdgendt
I tried with _netrc authentication, looks like the script fails with rate limit error in under 20 requests.
Whereas with --personal-access-token, script goes on successfully till 40 requests and the installation proceeds to completion.

[marc-hb]

I tried with _netrc authentication, looks like the script fails with rate limit error in under 20 requests.

I did some testing and I have a strong suspicion your .netrc file is invalid or misplaced.

It took me a while but I found a couple ways to test much faster and more reliable than downloading the SDK repeatedly.

I spent time testing this because the .netrc really matters: it's superior to --personal-access-token in pretty much every way for pretty much everyone. So, I would really like you to add the following text "... or use a .netrc file". Just mentioning that file and that's all, nothing else.

Please try this:

python3 -c 'import requests; print(requests.get("https://api.github.com/user/issues").content)'

    # Bad .netrc OR bad token shows this:
    b'{\r\n  "message": "Requires authentication",\r\n  "documentation_url": "https://docs.github.com/rest",\r\n  "status": "401"\r\n}'

   # Good .netrc AND good token returns a list (empty or not)
    b'[ ...  ]'

You can also compare these two commands:

curl -v --netrc https://api.github.com/user/issues
curl -v         https://api.github.com/user/issues

When using -n or --netrc you see additional "authorization" fields like this:

* [HTTP/2] [1] [authorization: Basic ....
* [HTTP/2] [1] ...
* [HTTP/2] [1] ...
> GET / HTTP/2
> Host: github.com
> Authorization: Basic ....

As long as the .netrc file is valid, you will see the "authorization" fields even when the token is wrong.

The .netrc file should look like this:

machine github.com
  login not-used
  password add token here
  
machine api.github.com
  login not-used-either
  password same token as above

Don't forget the indentation.

Obviously, make sure the .netrc file is readable only by you.

BTW I think _netrc is the older name but https://docs.python-requests.org/en/latest/user/authentication/#netrc-authentication claims to support both so it should hopefully not matter.

[3V3RYONE]

Thanks @marc-hb
I was able to run the installation script over 40 times with the .netrc file. I was only having github.com entry in my netrc file, adding api.github.com entry worked for me. I have updated the commit to hint about netrc as well.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud