feat(auth/githubapp): support client ID as alternative to numeric app ID for JWT iss claim

[Erik-Schuetze]

Title: feat(auth/githubapp): support client ID as alternative to numeric app ID for JWT iss claim

---

GitHub's documentation now recommends using the client ID (e.g. Iv23liXXXXXXX) instead of
the numeric app ID as the iss claim when generating JWTs for GitHub App authentication:
docs page for github.com
docs page for GHE 3.20

Currently auth/githubapp/client.go only accepts a numeric githubAppID, parsed with
strconv.ParseInt and used as the integer JWT issuer.

Problem

Users migrating from PATs to GitHub Apps are storing credentials using the client ID because
that is what GitHub now surfaces and recommends. Having to separately look up the numeric app ID
just for Flux is unnecessary friction, and the numeric ID is an internal identifier that GitHub
themselves are steering users away from.

Proposed change

Add an optional githubAppClientID secret key. If present and githubAppID is absent, use it
as the string iss claim in the JWT. The GitHub API accepts both forms.

Concretely in auth/githubapp/client.go:

• Add KeyAppClientID = "githubAppClientID" constant
• Store it as a clientID string field on Client
• In WithAppData, populate it when present
• In New, accept either appID != 0 or clientID != "" as valid
• In createJWT, use the client ID string as iss when app ID is zero

No breaking change -- githubAppID continues to work exactly as today.

Context

This came up while migrating a Flux GitRepository from a PAT to a GitHub App on a GitHub
Enterprise Server 3.20 instance. When creating the GitHub App, the UI prominently shows the
client ID (e.g. Iv23liXXXXXXX) as the app identifier. The numeric app ID is a secondary field
that users have to actively look for. Supporting githubAppClientID in the secret would let users
use the credential GitHub presents to them directly, without an extra lookup step.

I would be happy to submit a PR if the approach looks reasonable.

[matheuscscp]

The approach looks reasonable to me.

But auth/githubapp is not the only package that needs changes, runtime/secret also does and the flux2 codebase as well:

https://github.com/search?q=repo%3Afluxcd%2Fflux2+githubappid&type=code

Also, a PR to update the GitRepository docs is needed as well:

https://fluxcd.io/flux/components/source/gitrepositories/#github

And if you're interested in contributing to Flux Operator, the ResourceSetInputProvider docs will also need an update:

https://fluxoperator.dev/docs/crd/resourcesetinputprovider/#github-app-authentication

[Erik-Schuetze]

Thanks for the pointers! I would actually like to implement this myself as we need it in our org.

Before I start should I open all PRs (pkg, flux2, website) upfront for parallel review, or do you prefer we go one at a time starting with fluxcd/pkg?

[matheuscscp]

I prefer like you would for a script that avoids getting rate-limited by some API: one at a time please :)

And docs for GitRepository are in the source-controller repo, not website.

[Erik-Schuetze]

I opened #1296 starting withfluxcd/pkg.

One design note worth to mention: rather than accepting both githubAppID and githubAppClientID and picking one, as stated in my issue originally, I made them mutually exclusive, enforced in New, the secret writer, and the secret reader.
They're two identifiers for the same app feeding a single JWT iss claim, so I tried to mirror the existing installationOwner / installationID handling. It keeps the behaviour unambiguous and avoids silently ignoring one identity when both are supplied.

The PR covers runtime/secrets and auth/githubapp so the key is usable end-to-end inside pkg, but I can also split it into two PRs if preferred.

[matheuscscp]

Thanks @Erik-Schuetze! Please ping me next week to review, this week I'm very busy