Expose GitHub App authentication for CI/CD publishers

[denelon]

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 Support fine-grained tokens #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.

[denelon]

Ran the follow-up spike I mentioned. Publisher-owned App installed only on the fork does NOT work for cross-fork PR create.

Setup

Created a throwaway GitHub App with the permissions from this issue (Contents R/W, Pull requests R/W, Metadata R, Workflows R/W), installed on denelon/winget-pkgs only. Minted an installation token, walked the same fork-write + cross-fork PR path as the #595 spike.

Fork-side ops are dramatically cleaner with an App

The workflows-scope 500s that plagued the fine-grained PAT case go away entirely — the App carries workflows=write natively:

Stage	FGPAT (spike 1)	App token (this spike)
Create branch	500 empty body	201 ✅
Update branch ref	500 empty body	200 ✅

So the CLI plumbing part of this issue is real value even beyond PAT rotation — it makes the whole fork side more robust.

Cross-fork PR create still fails, and the error is instructive

POST /repos/microsoft/winget-pkgs/pulls
HTTP/1.1 403 Forbidden
x-accepted-github-permissions: pull_requests=write

{"message":"Resource not accessible by integration",
 "documentation_url":"https://docs.github.com/rest/pulls/pulls#create-a-pull-request",
 "status":"403"}

Note the wording: "Resource not accessible by integration" (App context) vs. the FGPAT case's "Resource not accessible by personal access token" (user context). Same block, different auth path.

Implication: GitHub enforces pull_requests=write on the base repo. For an App integration that means the App must be installed on microsoft/winget-pkgs for cross-fork PR create to succeed. A publisher-owned App on the fork alone cannot do it.

What this means for this issue

There are two viable paths:

Path A — Microsoft-owned "WinGet Publisher" App installed on winget-pkgs

The WinGet team creates and hosts a central App, installs it on microsoft/winget-pkgs, and publishers install the same App on their forks. Wingetcreate accepts the publisher's installation private key (or a service that mints installation tokens on their behalf).

• Pros: works today, no GitHub platform changes, publishers get real token rotation, fork-side ops are cleaner
• Cons: Microsoft owns the App identity → PRs authored by a bot account (attribution has to move into PR body/commit metadata); abuse surface (anyone can install and submit); rate-limit / anti-abuse story needed

Path B — Keep this issue as-is (advanced use only)

Ship the CLI plumbing (GetGitHubAppInstallationAccessToken exposure). Publishers who somehow get an App installed on winget-pkgs (via approval process, integration partnership, whatever) can use it. Default recommendation stays classic PAT.

My read

Path A is the right answer for the publisher pain that motivated this issue, but it's a Microsoft trust/policy decision, not a wingetcreate-CLI decision. This issue's CLI plumbing part is still worth doing — it's necessary either way — but its value proposition changes from "use your own App" to "use the WinGet Publisher App we host."

Happy to help scope Path A into its own tracking issue if that's the direction.

---

Co-authored with an AI agent.