Document GitHub API rate limits and PAT usage

Update documentation to explain GitHub REST API rate limits and how to authenticate Evergreen requests. Added a new, expanded GitHub rate limit doc with guidance on creating personal access tokens, setting GITHUB_TOKEN/GH_TOKEN on Windows, macOS/Linux and in GitHub Actions, and how authentication raises the limit to 5,000 requests/hour. Clarified that Get-EvergreenApp and Update-Evergreen query GitHub (and may be rate limited), added verbose rate-limit output details, and linked relevant pages. Changes applied to docs/github.md, Get-EvergreenApp.md, Update-Evergreen.md, and issues.md.

Author: aaronparker

docs/github.md

@@ -3,30 +3,97 @@ layout: doc
 ---
 # Working with GitHub rate limits
 
-Over 150 applications supported by Evergreen are hosted on GitHub repositories or pull data from a GitHub repository for determining the latest version. Evergreen makes use of the GitHub REST API when requesting details for these applications.
+Over 150 applications supported by Evergreen are hosted on GitHub repositories or pull data from a GitHub repository to determine the latest version. Evergreen uses the GitHub REST API when querying details for these applications.
 
-GitHub implements rate limits on the API for unauthenticated requests. See [Rate limits for the REST API](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api) for details.
+Both `Get-EvergreenApp` and `Update-Evergreen` make requests to the GitHub REST API:
 
-## Authenticating to the GitHub API
+- `Get-EvergreenApp` queries GitHub releases and tags to return version and download details for applications hosted on GitHub
+- `Update-Evergreen` downloads the latest application functions and manifests from the [eucpilots/evergreen-apps](https://github.com/eucpilots/evergreen-apps) repository
 
-For environments that may consume more than 60 requests to the API in an hour, Evergreen supports authenticated requests by use of [personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) should be used.
+GitHub implements rate limits on the API for unauthenticated requests, allowing only 60 requests per hour per IP address. In environments where Evergreen is run frequently or across multiple sessions, this limit can be reached quickly. See [Rate limits for the REST API](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api) for details.
 
-A token that has read-only access to public repositories only is recommended. This should enable you to use a long expiry time; however, secure management of this token is recommended.
+Authenticating requests with a personal access token raises the limit to 5,000 requests per hour.
+
+## Creating a personal access token
+
+Evergreen supports authenticated requests using [personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) are recommended.
+
+A token with read-only access to public repositories is sufficient. No additional scopes or permissions are required. Because the token only needs read access to public repositories, a long expiry period is reasonable; however, secure management of the token is still recommended.
 
 ![Fine-grained personal access token](/img/github-pat.png)
 
-## GITHUB_TOKEN environment variable
+## Setting the GITHUB_TOKEN environment variable
+
+Evergreen reads the `GITHUB_TOKEN` or `GH_TOKEN` environment variables. Setting either variable with the value of the personal access token enables Evergreen to authenticate requests to the GitHub API automatically. Both `Get-EvergreenApp` and `Update-Evergreen` will use the token without any additional configuration.
+
+### Windows
+
+To set the variable for the current user persistently (survives across sessions and reboots):
+
+```powershell
+[System.Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "<your-token>", "User")
+```
+
+To set it for all users on the machine (requires administrator):
+
+```powershell
+[System.Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "<your-token>", "Machine")
+```
+
+The variable can also be set via **System Properties > Advanced > Environment Variables** in the Windows UI.
+
+To set it only for the current PowerShell session:
+
+```powershell
+$env:GITHUB_TOKEN = "<your-token>"
+```
+
+### macOS and Linux
+
+Add the following line to your shell profile (`~/.zshrc` for Zsh, `~/.bashrc` or `~/.bash_profile` for Bash) to set the variable persistently:
 
-Evergreen will use the token stored in the `GITHUB_TOKEN` or `GH_TOKEN` environment variables. Setting either of these variables with the value of the personal access token will allow Evergreen to use the token when querying the GitHub API, significantly increasing the number of available requests.
+```bash
+export GITHUB_TOKEN="<your-token>"
+```
+
+Reload the profile after saving:
 
-### GitHub Actions
+```bash
+source ~/.zshrc  # or source ~/.bashrc
+```
 
-Additionally, if you are running Evergreen in a GitHub Actions workflow, the `GITHUB_TOKEN` will be used, so no additional personal access tokens are required - [Use GITHUB_TOKEN for authentication in workflows](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token).
+To set it only for the current shell session:
+
+```bash
+export GITHUB_TOKEN="<your-token>"
+```
 
-For example, add the following code to the top of your workflow file:
+## GitHub Actions
+
+When running Evergreen in a GitHub Actions workflow, the `GITHUB_TOKEN` secret is automatically available and does not require a separate personal access token. See [Use GITHUB_TOKEN for authentication in workflows](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token).
+
+Add the following to the top of your workflow file to make the token available as an environment variable:
 
 ```yaml
 # Environment variables
 env:
   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
+
+Evergreen will pick up the variable automatically when the workflow runs.
+
+## Checking the rate limit status
+
+When running `Get-EvergreenApp` for an application that uses GitHub as its source, passing `-Verbose` will output the current number of remaining API requests:
+
+```powershell
+Get-EvergreenApp -Name "MicrosoftBicep" -Verbose
+```
+
+The verbose output will include a line similar to:
+
+```
+VERBOSE: Get-GitHubRateLimit: Remaining requests to the GitHub API: 58 of 60
+```
+
+When the rate limit is exhausted, Evergreen returns a `RateLimited` version object and outputs a warning. Setting `GITHUB_TOKEN` or `GH_TOKEN` before running Evergreen will resolve this.

docs/help/en-US/Get-EvergreenApp.md

@@ -26,6 +26,8 @@ The output from this function can be passed to Where-Object to filter for a spec
 
 `Get-EvergreenApp` uses official vendor sources including update APIs, web queries, and code repository locations to return details of a target application at run time.
 
+Over 150 applications supported by Evergreen are hosted on GitHub. For these applications, `Get-EvergreenApp` queries the GitHub REST API, which is subject to a rate limit of 60 unauthenticated requests per hour. Set the `GITHUB_TOKEN` or `GH_TOKEN` environment variable to a personal access token to authenticate requests and raise the limit to 5,000 requests per hour.
+
 ## EXAMPLES
 
 ### EXAMPLE 1
@@ -250,6 +252,10 @@ Site: https://eucpilots.com/evergreen-docs
 
 Author: Aaron Parker
 
+For applications that use GitHub as a source, `Get-EvergreenApp` queries the GitHub REST API. Set the `GITHUB_TOKEN` or `GH_TOKEN` environment variable to a personal access token to authenticate these requests and avoid rate limiting. See [Working with GitHub rate limits](https://eucpilots.com/evergreen-docs/github/) for details.
+
 ## RELATED LINKS
 
 [Use Evergreen](https://eucpilots.com/evergreen-docs/use/)
+
+[Working with GitHub rate limits](https://eucpilots.com/evergreen-docs/github/)

docs/help/en-US/Update-Evergreen.md

@@ -19,7 +19,9 @@ Update-Evergreen [-Force] [<CommonParameters>]
 
 ## DESCRIPTION
 
-Enables separation of the core Evergreen module from app-specific code and manifests. Downloads the latest versions of /Apps and /Manifests from a specified GitHub repository to a user-writable location (no admin required). By default, the local cache is downloaded to %LocalAppData%\Evergreen on Windows, and ~/.evergreen on macOS and Linux.
+Enables separation of the core Evergreen module from app-specific code and manifests. Downloads the latest versions of /Apps and /Manifests from the [eucpilots/evergreen-apps](https://github.com/eucpilots/evergreen-apps) GitHub repository to a user-writable location (no admin required). By default, the local cache is downloaded to %LocalAppData%\Evergreen on Windows, and ~/.evergreen on macOS and Linux.
+
+`Update-Evergreen` queries the GitHub REST API to check for and download updates. In environments where it is run frequently, GitHub's unauthenticated API rate limit of 60 requests per hour may be reached. Set the `GITHUB_TOKEN` or `GH_TOKEN` environment variable to a personal access token to authenticate requests and raise the limit to 5,000 requests per hour.
 
 ## EXAMPLES
 
@@ -75,4 +77,8 @@ Site: https://eucpilots.com/evergreen-docs
 
 Author: Aaron Parker
 
+`Update-Evergreen` uses the GitHub REST API to check for and download updates from the eucpilots/evergreen-apps repository. Set the `GITHUB_TOKEN` or `GH_TOKEN` environment variable to a personal access token to authenticate these requests. See [Working with GitHub rate limits](https://eucpilots.com/evergreen-docs/github/) for details.
+
 ## RELATED LINKS
+
+[Working with GitHub rate limits](https://eucpilots.com/evergreen-docs/github/)

docs/issues.md

@@ -21,9 +21,9 @@ Supports Windows platforms only - this function wraps `Resolve-DnsName` which is
 
 ### Get-GitHubRepoRelease
 
-`Get-GitHubRepoRelease` queries release information from a specified GitHub repository to return version and binaries or is used to source the version number for some applications. This function uses an unauthenticated session to the GitHub REST API, thus requests will be [rate limited]. Using the `-Verbose` parameter with `Get-EvergreenApp` for those applications that use GitHub as the source, will display the number of available requests to the API.
+`Get-GitHubRepoRelease` queries release information from a specified GitHub repository to return version and binaries or is used to source the version number for some applications. By default, requests to the GitHub REST API are unauthenticated and subject to a rate limit of 60 requests per hour. Using the `-Verbose` parameter with `Get-EvergreenApp` for those applications that use GitHub as the source will display the number of available API requests remaining.
 
-Updating `Get-GitHubRepoRelease` to support authenticated requests is planned for a future release.
+Authenticated requests are supported via the `GITHUB_TOKEN` or `GH_TOKEN` environment variables, which raise the rate limit to 5,000 requests per hour. See [Working with GitHub rate limits](/github) for setup instructions.
 
 ## Application Functions