feat: authenticate GitHub API requests using GH_TOKEN/GITHUB_TOKEN in PowerShell module (#5949)

wmmc88 · wmmc88 · commit a8aa27701a87 · 2026-03-03T10:42:33.000-08:00
Add automatic detection of GH_TOKEN and GITHUB_TOKEN environment
variables in the PowerShell module GitHubClient to authenticate
GitHub API requests, increasing rate limits from 60 to 5,000/hour.

Also add documentation to Repair-WinGetPackageManager and
Assert-WinGetPackageManager help docs describing the environment
variable behavior.
diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt
@@ -388,6 +388,7 @@ nsis
 NTFS
 objbase
 objidl
+octokitnet
 ofile
 oid
 omus
@@ -646,6 +647,7 @@ winreg
 winrtact
 winstring
 WMI
+wmmc
 wnd
 WNDCLASS
 WNDCLASSEX
diff --git a/doc/ReleaseNotes.md b/doc/ReleaseNotes.md
@@ -32,6 +32,10 @@ match criteria that factor into the result ordering. This will prevent them from
 
 Added a new `--no-progress` command-line flag that disables all progress reporting (progress bars and spinners). This flag is universally available on all commands and takes precedence over the `visual.progressBar` setting. Useful for automation scenarios or when running WinGet in environments where progress output is undesirable.
 
+### Authenticated GitHub API requests in PowerShell module
+
+The PowerShell module now automatically uses `GH_TOKEN` or `GITHUB_TOKEN` environment variables to authenticate GitHub API requests. This increases the rate limit from 60 to 5,000 requests per hour, preventing failures in CI/CD pipelines (e.g., GitHub Actions). Use `-Verbose` to see which token is being used.
+
 ## Bug Fixes
 
 <!-- Nothing yet! -->
diff --git a/doc/specs/#5949 - Authenticated GitHub API Requests for PowerShell Module.md b/doc/specs/#5949 - Authenticated GitHub API Requests for PowerShell Module.md
@@ -0,0 +1,96 @@
+---
+author: Melvin Wang @wmmc88
+created on: 2026-02-09
+last updated: 2026-02-26
+issue id: 5949
+---
+
+# Authenticated GitHub API Requests for PowerShell Module
+
+For [#5949](https://github.com/microsoft/winget-cli/issues/5949).
+
+## Abstract
+
+This spec describes adding support for authenticated GitHub API requests in the WinGet PowerShell module. The module's `GitHubClient` helper will automatically detect `GH_TOKEN` or `GITHUB_TOKEN` environment variables and use them to authenticate Octokit API calls, significantly increasing the GitHub API rate limit.
+
+## Inspiration
+
+Users running `Repair-WinGetPackageManager` in GitHub Actions pipelines hit unauthenticated rate limits (60 requests/hour). Authenticated requests allow 5,000 requests/hour. The GitHub CLI (`gh`) already uses `GH_TOKEN` and `GITHUB_TOKEN` for the same purpose, and GitHub Actions automatically provides `GITHUB_TOKEN`.
+
+See: https://github.com/microsoft/windows-drivers-rs/actions/runs/20531244312/job/58982795057#step:3:43
+
+## Solution Design
+
+The `GitHubClient` class in `Microsoft.WinGet.Client.Engine` is updated to:
+
+1. Read all known token environment variables (`GH_TOKEN`, `GITHUB_TOKEN`) on construction.
+2. Log the presence or absence of each token via `StreamType.Verbose`.
+3. Select the token to use based on precedence (`GH_TOKEN` > `GITHUB_TOKEN`), matching GitHub CLI behavior.
+4. Log which token source is being used, or that no token was found.
+5. Set `Octokit.GitHubClient.Credentials` if a token is available.
+
+Token resolution is extracted into a static `ResolveGitHubToken` method for testability.
+
+### Token Precedence
+
+`GH_TOKEN` takes precedence over `GITHUB_TOKEN`, matching the [GitHub CLI convention](https://cli.github.com/manual/gh_help_environment). This is because `GH_TOKEN` is explicitly set by users, while `GITHUB_TOKEN` is automatically provided by GitHub Actions and may have more restricted permissions.
+
+### Logging
+
+All logging uses `StreamType.Verbose` via the existing `PowerShellCmdlet.Write` pattern, visible when users pass `-Verbose` to cmdlets. Example output:
+
+```
+VERBOSE: GH_TOKEN environment variable: not found
+VERBOSE: GITHUB_TOKEN environment variable: found
+VERBOSE: Using authenticated GitHub API requests via GITHUB_TOKEN environment variable.
+```
+
+### Files Changed
+
+- `src/PowerShell/Microsoft.WinGet.Client.Engine/Helpers/GitHubClient.cs` — Token resolution logic and logging.
+- `src/PowerShell/Microsoft.WinGet.Client.Engine/Properties/AssemblyInfo.cs` — `InternalsVisibleTo` for unit tests.
+- `src/PowerShell/Microsoft.WinGet.Client.Engine/Commands/WinGetPackageManagerCommand.cs` — Pass `PowerShellCmdlet` to `GitHubClient` constructor.
+- `src/PowerShell/Microsoft.WinGet.Client.Engine/Helpers/AppxModuleHelper.cs` — Pass `PowerShellCmdlet` to `GitHubClient` constructor.
+- `src/PowerShell/Microsoft.WinGet.UnitTests/GitHubClientTests.cs` — Unit tests for token resolution.
+
+## UI/UX Design
+
+No new command-line arguments or user-facing changes. The feature is automatic: if `GH_TOKEN` or `GITHUB_TOKEN` is set in the environment, authenticated requests are used. Users can see which token is being used by running any repair/assert cmdlet with `-Verbose`.
+
+### Accessibility
+
+No impact on accessibility.
+
+### Security
+
+- Tokens are never logged or written to output; only the environment variable name is logged.
+- Token values are read from environment variables which are a standard secure mechanism for passing secrets in CI/CD environments.
+- Whitespace-only token values are treated as unset to prevent accidental empty-credential authentication.
+
+### Reliability
+
+Improves reliability by reducing GitHub API rate limit failures in CI/CD pipelines. Unauthenticated requests are still used as a fallback when no tokens are set.
+
+### Compatibility
+
+Fully backward compatible. When no token environment variables are set, behavior is identical to the previous implementation.
+
+### Performance, Power, and Efficiency
+
+No measurable impact. A single environment variable read per `GitHubClient` construction.
+
+## Potential Issues
+
+- If a user has an expired or revoked token in `GH_TOKEN`/`GITHUB_TOKEN`, API calls will fail with a 401 rather than falling back to unauthenticated. This matches GitHub CLI behavior and is the expected outcome.
+
+## Future considerations
+
+- Support for additional token sources (e.g., `gh auth token` integration, Windows Credential Manager).
+- Applying authenticated requests to other parts of the WinGet client beyond the PowerShell module.
+
+## Resources
+
+- [GitHub API rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api)
+- [GitHub CLI environment variables](https://cli.github.com/manual/gh_help_environment)
+- [Octokit.NET authenticated access](https://octokitnet.readthedocs.io/en/latest/getting-started/#authenticated-access)
+- [Issue #5949](https://github.com/microsoft/winget-cli/issues/5949)
diff --git a/src/PowerShell/Help/Microsoft.WinGet.Client/Assert-WinGetPackageManager.md b/src/PowerShell/Help/Microsoft.WinGet.Client/Assert-WinGetPackageManager.md
@@ -142,6 +142,19 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## NOTES
 
+### Authenticated GitHub API requests
+
+When using the `-Latest` or `-Version` parameters, this cmdlet makes GitHub API requests to query
+release information. Unauthenticated requests are limited to 60 per hour, which can cause failures
+in CI/CD pipelines. If the `GH_TOKEN` or `GITHUB_TOKEN` environment variable is set, the cmdlet
+automatically uses it to authenticate requests, increasing the rate limit to 5,000 per hour.
+
+`GH_TOKEN` takes precedence over `GITHUB_TOKEN`, matching
+[GitHub CLI behavior](https://cli.github.com/manual/gh_help_environment). In GitHub Actions,
+`GITHUB_TOKEN` is automatically available.
+
+Use `-Verbose` to see which token source is being used.
+
 ## RELATED LINKS
 
 [Get-WinGetVersion](Get-WinGetVersion.md)
diff --git a/src/PowerShell/Help/Microsoft.WinGet.Client/Repair-WinGetPackageManager.md b/src/PowerShell/Help/Microsoft.WinGet.Client/Repair-WinGetPackageManager.md
@@ -166,6 +166,19 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## NOTES
 
+### Authenticated GitHub API requests
+
+This cmdlet makes GitHub API requests to query release information. Unauthenticated requests are
+limited to 60 per hour, which can cause failures in CI/CD pipelines. If the `GH_TOKEN` or
+`GITHUB_TOKEN` environment variable is set, the cmdlet automatically uses it to authenticate
+requests, increasing the rate limit to 5,000 per hour.
+
+`GH_TOKEN` takes precedence over `GITHUB_TOKEN`, matching
+[GitHub CLI behavior](https://cli.github.com/manual/gh_help_environment). In GitHub Actions,
+`GITHUB_TOKEN` is automatically available.
+
+Use `-Verbose` to see which token source is being used.
+
 ## RELATED LINKS
 
 [Get-WinGetVersion](Get-WinGetVersion.md)
diff --git a/src/PowerShell/Microsoft.WinGet.Client.Engine/Commands/WinGetPackageManagerCommand.cs b/src/PowerShell/Microsoft.WinGet.Client.Engine/Commands/WinGetPackageManagerCommand.cs
@@ -43,7 +43,7 @@ public void AssertUsingLatest(bool preRelease)
             var runningTask = this.RunOnMTA(
                 async () =>
                 {
-                    var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli);
+                    var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli, this);
                     string expectedVersion = await gitHubClient.GetLatestReleaseTagNameAsync(preRelease);
                     this.Assert(expectedVersion);
                     return true;
@@ -73,7 +73,7 @@ public void RepairUsingLatest(bool preRelease, bool allUsers, bool force)
             var runningTask = this.RunOnMTA(
                 async () =>
                 {
-                    var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli);
+                    var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli, this);
                     string expectedVersion = await gitHubClient.GetLatestReleaseTagNameAsync(preRelease);
                     await this.RepairStateMachineAsync(expectedVersion, allUsers, force);
                     return true;
@@ -98,7 +98,7 @@ public void Repair(string expectedVersion, bool allUsers, bool force, bool inclu
                     if (!string.IsNullOrWhiteSpace(expectedVersion))
                     {
                         this.Write(StreamType.Verbose, $"Attempting to resolve version '{expectedVersion}'");
-                        var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli);
+                        var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli, this);
                         try
                         {
                             var resolvedVersion = await gitHubClient.ResolveVersionAsync(expectedVersion, includePrerelease);
@@ -224,7 +224,7 @@ private async Task InstallAsync(string toInstallVersion, bool allUsers, bool for
             // this particular case we need to.
             if (string.IsNullOrEmpty(toInstallVersion))
             {
-                var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli);
+                var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli, this);
                 toInstallVersion = await gitHubClient.GetLatestReleaseTagNameAsync(false);
             }
 
diff --git a/src/PowerShell/Microsoft.WinGet.Client.Engine/Helpers/AppxModuleHelper.cs b/src/PowerShell/Microsoft.WinGet.Client.Engine/Helpers/AppxModuleHelper.cs
@@ -266,7 +266,7 @@ private static Tuple<string, string> GetXamlDependencyVersionInfo(string release
 
         private async Task AddProvisionPackageAsync(string releaseTag)
         {
-            var githubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli);
+            var githubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli, this.pwshCmdlet);
             var release = await githubClient.GetReleaseAsync(releaseTag);
 
             var bundleAsset = release.GetAsset(MsixBundleName);
@@ -325,7 +325,7 @@ private async Task AddAppInstallerBundleAsync(string releaseTag, bool downgrade,
 
             try
             {
-                var githubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli);
+                var githubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli, this.pwshCmdlet);
                 var release = await githubClient.GetReleaseAsync(releaseTag);
 
                 var bundleAsset = release.GetAsset(MsixBundleName);
@@ -560,7 +560,7 @@ private async Task InstallVCLibsDependenciesFromUriAsync()
         // Returns a boolean value indicating whether dependencies were successfully installed from the GitHub release assets.
         private async Task<bool> InstallDependenciesFromGitHubArchive(string releaseTag)
         {
-            var githubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli);
+            var githubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli, this.pwshCmdlet);
             var release = await githubClient.GetReleaseAsync(releaseTag);
 
             ReleaseAsset? dependenciesJsonAsset = release.TryGetAsset(DependenciesJsonName);
@@ -667,7 +667,7 @@ private async Task InstallUiXamlAsync(string releaseTag)
             var uiXamlObjs = this.GetAppxObject(xamlPackageName);
             if (uiXamlObjs is null)
             {
-                var githubRelease = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.UiXaml);
+                var githubRelease = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.UiXaml, this.pwshCmdlet);
 
                 var xamlRelease = await githubRelease.GetReleaseAsync(xamlReleaseTag);
 
diff --git a/src/PowerShell/Microsoft.WinGet.Client.Engine/Helpers/GitHubClient.cs b/src/PowerShell/Microsoft.WinGet.Client.Engine/Helpers/GitHubClient.cs
@@ -22,19 +22,64 @@ internal class GitHubClient
         private readonly string owner;
         private readonly string repo;
         private readonly IGitHubClient gitHubClient;
+        private readonly PowerShellCmdlet? pwshCmdlet;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="GitHubClient"/> class.
         /// </summary>
         /// <param name="owner">Owner.</param>
         /// <param name="repo">Repository.</param>
-        public GitHubClient(string owner, string repo)
+        /// <param name="pwshCmdlet">Optional PowerShell cmdlet for logging.</param>
+        public GitHubClient(string owner, string repo, PowerShellCmdlet? pwshCmdlet = null)
         {
-            this.gitHubClient = new Octokit.GitHubClient(new ProductHeaderValue(HttpClientHelper.UserAgent));
+            this.pwshCmdlet = pwshCmdlet;
+            var octokitClient = new Octokit.GitHubClient(new ProductHeaderValue(HttpClientHelper.UserAgent));
+
+            string? token = ResolveGitHubToken(pwshCmdlet);
+            if (!string.IsNullOrWhiteSpace(token))
+            {
+                octokitClient.Credentials = new Credentials(token);
+            }
+
+            this.gitHubClient = octokitClient;
             this.owner = owner;
             this.repo = repo;
         }
 
+        /// <summary>
+        /// Reads all known GitHub token environment variables, logs their presence,
+        /// and selects the one to use based on precedence.
+        /// GH_TOKEN takes precedence over GITHUB_TOKEN, matching GitHub CLI behavior.
+        /// See: https://cli.github.com/manual/gh_help_environment.
+        /// </summary>
+        /// <param name="pwshCmdlet">Optional PowerShell cmdlet for logging.</param>
+        /// <returns>The selected token value, or null if none found.</returns>
+        internal static string? ResolveGitHubToken(PowerShellCmdlet? pwshCmdlet = null)
+        {
+            string? ghToken = Environment.GetEnvironmentVariable("GH_TOKEN");
+            string? githubToken = Environment.GetEnvironmentVariable("GITHUB_TOKEN");
+
+            bool hasGhToken = !string.IsNullOrWhiteSpace(ghToken);
+            bool hasGithubToken = !string.IsNullOrWhiteSpace(githubToken);
+
+            pwshCmdlet?.Write(StreamType.Verbose, $"GH_TOKEN environment variable: {(hasGhToken ? "found" : "not found")}");
+            pwshCmdlet?.Write(StreamType.Verbose, $"GITHUB_TOKEN environment variable: {(hasGithubToken ? "found" : "not found")}");
+
+            if (hasGhToken)
+            {
+                pwshCmdlet?.Write(StreamType.Verbose, "Using authenticated GitHub API requests via GH_TOKEN environment variable.");
+                return ghToken;
+            }
+            else if (hasGithubToken)
+            {
+                pwshCmdlet?.Write(StreamType.Verbose, "Using authenticated GitHub API requests via GITHUB_TOKEN environment variable.");
+                return githubToken;
+            }
+
+            pwshCmdlet?.Write(StreamType.Verbose, "No GitHub token found. Using unauthenticated GitHub API requests.");
+            return null;
+        }
+
         /// <summary>
         /// Gets a release.
         /// </summary>
diff --git a/src/PowerShell/Microsoft.WinGet.Client.Engine/Properties/AssemblyInfo.cs b/src/PowerShell/Microsoft.WinGet.Client.Engine/Properties/AssemblyInfo.cs
@@ -4,9 +4,14 @@
 // </copyright>
 // -----------------------------------------------------------------------------
 
+using System.Runtime.CompilerServices;
 #if NET
-
 using System.Runtime.Versioning;
+#endif
+
+[assembly: InternalsVisibleTo("Microsoft.WinGet.UnitTests")]
+
+#if NET
 
 // Forcibly set the target and supported platforms due to the internal build setup.
 // Keep in sync with project versions.
diff --git a/src/PowerShell/Microsoft.WinGet.UnitTests/GitHubClientTests.cs b/src/PowerShell/Microsoft.WinGet.UnitTests/GitHubClientTests.cs

Original file line number	Diff line number	Diff line change
`@@ -43,7 +43,7 @@ public void AssertUsingLatest(bool preRelease)`
`43`	`43`	`var runningTask = this.RunOnMTA(`
`44`	`44`	`async () =>`
`45`	`45`	`{`
`46`		`- var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli);`
	`46`	`+ var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli, this);`
`47`	`47`	`string expectedVersion = await gitHubClient.GetLatestReleaseTagNameAsync(preRelease);`
`48`	`48`	`this.Assert(expectedVersion);`
`49`	`49`	`return true;`
`@@ -73,7 +73,7 @@ public void RepairUsingLatest(bool preRelease, bool allUsers, bool force)`
`73`	`73`	`var runningTask = this.RunOnMTA(`
`74`	`74`	`async () =>`
`75`	`75`	`{`
`76`		`- var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli);`
	`76`	`+ var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli, this);`
`77`	`77`	`string expectedVersion = await gitHubClient.GetLatestReleaseTagNameAsync(preRelease);`
`78`	`78`	`await this.RepairStateMachineAsync(expectedVersion, allUsers, force);`
`79`	`79`	`return true;`
`@@ -98,7 +98,7 @@ public void Repair(string expectedVersion, bool allUsers, bool force, bool inclu`
`98`	`98`	`if (!string.IsNullOrWhiteSpace(expectedVersion))`
`99`	`99`	`{`
`100`	`100`	`this.Write(StreamType.Verbose, $"Attempting to resolve version '{expectedVersion}'");`
`101`		`- var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli);`
	`101`	`+ var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli, this);`
`102`	`102`	`try`
`103`	`103`	`{`
`104`	`104`	`var resolvedVersion = await gitHubClient.ResolveVersionAsync(expectedVersion, includePrerelease);`
`@@ -224,7 +224,7 @@ private async Task InstallAsync(string toInstallVersion, bool allUsers, bool for`
`224`	`224`	`// this particular case we need to.`
`225`	`225`	`if (string.IsNullOrEmpty(toInstallVersion))`
`226`	`226`	`{`
`227`		`- var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli);`
	`227`	`+ var gitHubClient = new GitHubClient(RepositoryOwner.Microsoft, RepositoryName.WinGetCli, this);`
`228`	`228`	`toInstallVersion = await gitHubClient.GetLatestReleaseTagNameAsync(false);`
`229`	`229`	`}`
`230`	`230`