Expose GitHub App authentication for CI/CD publishers

Description of the new feature / enhancement

Expose the existing GitHub App authentication path in the winget-create CLI so publishers running wingetcreate in CI/CD can authenticate with a GitHub App installation token instead of a personal access token.

Why

Publishers running wingetcreate from GitHub Actions / Azure Pipelines / other CI keep hitting the same problem: they have to store a long-lived classic PAT (fine-grained PATs don't work today — see #595 and the validation evidence I posted there), and every time it expires their release pipeline breaks. That drives them toward "just set the PAT to never expire," which is exactly the security posture we don't want.

GitHub Apps solve this cleanly:

• Installation tokens rotate automatically (1-hour lifetime, minted on demand from a signed JWT).
• The App is scoped to specific repos and specific permissions — narrower blast radius than a classic PAT.
• The private key can be stored as a CI secret and used across many repos/publishers without human-in-the-loop rotation.

What already exists

The core code is already in the repo — it just isn't reachable from the CLI:

• GitHub.GetGitHubAppInstallationAccessToken(pemKey, appId, wingetRepoOwner, wingetRepo) mints a JWT, gets the installation on the target repo, and returns a usable installation token.
• GitHub.GetJwtToken handles the RSA/JWT signing (via the Jose dependency already in the project).
• The test harness (GitHubTestsBase.cs) uses this exact path today via a WINGET_CREATE_APP_KEY env var, so it's proven working for real submit flows.

Proposed technical implementation details

1. CLI options / env vars on submit-capable commands (update, submit, new, new-locale, update-locale):

• --github-app-id <id> or env WINGET_CREATE_GITHUB_APP_ID
• --github-app-private-key-file <path> or env WINGET_CREATE_GITHUB_APP_PRIVATE_KEY_PATH
  • File-based to avoid multi-line env-var pain in CI secrets

2. Token resolution precedence in BaseCommand.LoadGitHubClient() (or equivalent):

1. If --token / WINGET_CREATE_GITHUB_TOKEN set → use as-is (PAT path)
2. Else if App ID + private key present → call GetGitHubAppInstallationAccessToken and use the returned installation token
3. Else → fall back to cached OAuth token / OAuth device flow (interactive path)

3. Docs in doc/token.md (or new doc/github-app.md):

• Step-by-step: create App at github.com/settings/apps/new, set permissions (Contents R/W, Pull requests R/W, Metadata R, Workflows R/W — the workflows scope matters because winget-pkgs contains .github/workflows/ files, per the #595 spike), generate private key, install on the publisher's fork of winget-pkgs.
• CI/CD examples for GitHub Actions and Azure Pipelines showing how to load the private key from a secret file.
• Guidance on the trust model: publisher-owned App vs. central Microsoft-owned App.

4. Optional follow-ups (not required for MVP):

• Installation token caching to avoid re-minting on rapid successive commands (probably not worth it — installation tokens are 1h and most CI runs are minutes).
• A wingetcreate app --setup helper subcommand mirroring wingetcreate token -s if there's demand for discoverability.

Open validation

One thing still worth confirming with a small spike: does POST /repos/microsoft/winget-pkgs/pulls accept a fork-installed App's installation token cleanly for cross-fork PR creation? The existing test suite bypasses this by using SubmitPRToFork = false. Happy to run the validation the same way I did for #595 if this is picked up.

Effort estimate

• CLI plumbing + precedence: ~150 lines
• Docs + CI examples: half a day
• Validation spike (cross-fork PR with installation token): ~2 hours
• Total: ~1 dev-day for MVP, ~3 days including polished docs and CI/CD examples.

Relationship to #595

This is the actionable near-term fix for the publisher pain that #595 is tracking. Fine-grained PATs remain blocked at the GitHub platform level (roadmap#600), so #595 stays open as a "when GitHub ships" tracking issue. This issue tracks the fix we can actually ship today.

---

Co-authored with an AI agent.

Start with src/WingetCreateCore/Common/GitHub.cs and BaseCommand.LoadGitHubClient (or its equivalent), then review the GitHubTestsBase.cs harness and the submit-capable commands. Trace the existing app-token path and define the CLI/environment precedence before checking doc/token.md. Done means app credentials work for the listed commands, PAT and OAuth fallbacks remain intact, and the GitHub Actions and Azure Pipelines guidance is documented; confirm cross-fork PR behavior separately.