Skip to content

Add GitHub Apps authentication as an alternative to personal access tokens - #59

Merged
Naoray merged 6 commits into
Naoray:mainfrom
AquaroTorres:main
Aug 17, 2026
Merged

Add GitHub Apps authentication as an alternative to personal access tokens#59
Naoray merged 6 commits into
Naoray:mainfrom
AquaroTorres:main

Conversation

@AquaroTorres

@AquaroTorres AquaroTorres commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

This PR adds support for authenticating with a GitHub App installation as an alternative to a personal access token (PAT). Many teams prefer GitHub Apps over PATs because they're scoped to specific repos/permissions, aren't tied to an individual user's account, and their tokens auto-expire — this brings that option to the package without changing
anything for existing PAT users.

What's new

  • github_app config block, used instead of token:
'github_app' => [
    'client_id' => env('GITHUB_MONOLOG_APP_CLIENT_ID'),
    'installation_id' => env('GITHUB_MONOLOG_APP_INSTALLATION_ID'),
    'private_key' => env('GITHUB_MONOLOG_APP_PRIVATE_KEY'),
    // or: 'private_key_path' => env('GITHUB_MONOLOG_APP_PRIVATE_KEY_PATH'),
],
  • GithubAppTokenProvider: signs a short-lived RS256 JWT for the app (using PHP's built-in openssl_sign; ext-openssl is a required PHP extension, and no third-party Composer package was added) and exchanges it for an installation access token via POST /app/installations/{id}/access_tokens.
  • Token caching: installation tokens are valid for 60 minutes on GitHub's side; this caches them for 50 minutes (using the same cache store/prefix as the existing deduplication feature) to avoid re-authenticating on every request while staying safely under the real expiry.
  • TokenProviderInterface abstraction: GithubIssueHandlerFactory now resolves either a PersonalAccessTokenProvider (existing PAT behavior, unchanged) or a GithubAppTokenProvider depending on config — github_app takes precedence if both are set.
  • Private key flexibility: accepts the PEM contents directly, base64-encoded PEM (handy for single-line .env values), or a file path via private_key_path.
  • README updates: setup walkthrough for creating the App, installing it, and finding the installation ID (including the organization-owned case), plus a note that GitHub's Client ID (not just the numeric App ID) works for the JWT iss claim, matching GitHub's current UI.

Backward compatibility
Fully opt-in — token continues to work exactly as before for anyone not using github_app. No breaking changes to the public API or existing config.

Testing

  • New tests for GithubAppTokenProvider (JWT signing/verification, token caching, error handling for invalid keys and malformed API responses).
  • Extended GithubIssueHandlerFactoryTest for the github_app resolution path, precedence over token, and the private_key_path fallback.
  • Full suite passes (358 tests, 1096 assertions), pint clean.
  • Long-lived workers: Handler refreshes cached GitHub App credentials once per logical write, allowing expired installation tokens to be replaced between writes.

claude and others added 6 commits July 28, 2026 00:51
Allow the package to authenticate as a GitHub App installation instead
of a personal access token. A signed RS256 JWT is exchanged for a
short-lived installation access token, which is cached until shortly
before it expires.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LaDzXAiGnyQ25uJ4aHYwZ3
…okup

GitHub now surfaces the app's Client ID (not the numeric App ID) as the
primary identifier on the app settings page. Rename github_app.id to
github_app.client_id (and the matching env var/constructor param) to
match, and expand the README with concrete steps for finding the
installation ID for both personal and organization-owned apps.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LaDzXAiGnyQ25uJ4aHYwZ3
Rename GitHub App id config to client_id, document installation ID lookup
@Naoray
Naoray merged commit 273fbc4 into Naoray:main Aug 17, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants