Support GitHub App installation tokens for the GitHub forge

[slayerjain]

This adds first-class GitHub App support to the GitHub forge: when WOODPECKER_GITHUB_APP_ID and WOODPECKER_GITHUB_APP_PRIVATE_KEY(_FILE) are configured, Woodpecker authenticates repo-scoped server-side operations and clone credentials with installation access tokens instead of the repo owner's personal OAuth token. User login stays on the OAuth flow, and repositories the app is not installed on transparently fall back to the current user-token behavior.

Why

Today every server-side API call (commit statuses, pipeline config fetching, changed-file lookups) and every clone runs on the OAuth token of the user who enabled the repository. For larger organizations this has three structural problems:

• all repos of an org share one user's 5,000 req/h rate limit
• pipelines break when that user leaves the org or loses access (see the SAML variant in Unauthorized user tokens preventing builds from running when protected by SAML enforcement #3804, and GitHub: Stale user token preventing builds from running (?) #2482/GitHub: Stale user token prevent builds from running #2488/GitHub backend: unknown error/401 bad credentials after some time #4079)
• commit statuses appear under a personal account instead of a bot identity

Installation tokens get per-installation rate limits that scale with repository count, survive user departure, and post statuses as the app's bot account. This also allows removing the long-stale docs warning against GitHub Apps (added in #2499, obsolete since #3811 introduced refresh-token support).

What changed

• server/forge/github/app.go: authenticates as the app (RS256 JWT via the already-vendored golang-jwt/jwt/v5; client id or app id as issuer, backdated iat per GitHub's guidance) and mints installation access tokens through the existing go-github dependency — no new module needed. Installation lookups and tokens are cached with validity margins (5 min for API calls, 45 min for clone credentials); "not installed" results are negative-cached and uninstall/suspension invalidates the cache and falls back gracefully.
• Token selection wired into Netrc (x-access-token), Status, File/Dir, Branches, BranchHead, PullRequests and the webhook changed-files/tag loaders. The loaders skip the repo-owner DB lookup entirely when the app covers the repo. Tokens are installation-wide on purpose so same-org submodule clones keep working.
• Config plumbing: new env vars → AdditionalOptions["app-id"/"app-private-key"] (same channel as the bitbucket-dc machine account) → github.Opts. No DB migration needed. Private keys are accepted as PEM or base64-encoded PEM, including keys whose newlines were mangled by env files or input fields.
• The private key is write-only in the API/UI (like oauth_client_secret): responses replace it with an app-private-key-set marker, and updates that omit it keep the stored key. Clearing the app id disables app auth again.
• Validation: invalid app credentials are rejected at save time in the forge API (HTTP 400) and fail fast at boot for env-managed forges, instead of breaking every forge operation at runtime.
• New admin endpoint GET /forges/{id}/app-health plus a "Test GitHub App" button in the admin forge form so operators can verify the credentials actually work.
• Admin UI fields (app id + multi-line private key), docs rewrite of the GitHub App section (required permissions, webhook note, token-expiry caveat), fixture-based unit tests for the token flow (JWT signature verification, caching, fallback, PEM variants) and API tests for redaction/merge/health.

Notes

• Webhook handling is unchanged: Woodpecker keeps creating per-repo webhooks, the app's own webhook stays disabled. Org-level auto-enrollment via app installation events (Handle Github organizational webhooks to autoenable new repos #71) would be a natural follow-up but is out of scope here.
• A token cached before an app is suspended/uninstalled can be served until its validity margin passes (bounded by the 10-minute forge cache); this matches the behavior of ghinstallation-based tools (Atlantis, ArgoCD).

[woodpecker-bot]

Surge PR preview deployment succeeded. View it at https://woodpecker-ci-woodpecker-pr-6806.surge.sh

[codecov]

Codecov Report

❌ Patch coverage is 93.35443% with 21 lines in your changes missing coverage. Please review.
✅ Project coverage is 48.31%. Comparing base (adbc365) to head (3bed999).
⚠️ Report is 7 commits behind head on main.

Files with missing lines	Patch %	Lines
server/forge/github/app.go	92.68%	6 Missing and 3 partials ⚠️
server/forge/github/github.go	91.66%	5 Missing and 2 partials ⚠️
server/api/forge.go	94.93%	3 Missing and 1 partial ⚠️
server/router/api.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6806      +/-   ##
==========================================
+ Coverage   47.30%   48.31%   +1.00%     
==========================================
  Files         440      441       +1     
  Lines       29726    30007     +281     
==========================================
+ Hits        14062    14498     +436     
+ Misses      14496    14313     -183     
- Partials     1168     1196      +28     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[slayerjain]

This seems to be working fine in Keploy on-prem CI. Please let me know if any changes needed before merge.

[6543]

... for cloning repos

this could have security implications and need to be looked at

[slayerjain]

Makes sense. I have narrowed the minted token to just the job's repo and with read-only content permissions.

[slayerjain]

Please resolve this if you think it's fine.