Github Client Laravel Package

Getting Started

1. Install and configure – composer require the package (v3.1.0 requires Laravel 13, Saloon ^4.3, and php-jwt ^7), then publish its config if available. Set either a GITHUB_TOKEN for personal access token (PAT) auth, or GitHub App credentials (GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_INSTALLATION_ID) for app-based auth.
2. Look first at docs/ARCHITECTURE.md – the new doc explains how connectors, authentication strategies, and requests fit together. Also skim the CHANGELOG.md for the v3.1.0 auth-status fix and error guidance changes.
3. First use case – resolve the connector from the container and run a simple call, e.g. list repositories or fetch an issue. If you're using a GitHub App, confirm the connector reports authenticated status correctly (the v3.1.0 fix) before wiring it into automation.

Implementation Patterns

• Inject the connector, not raw HTTP – resolve the connector via Laravel's container (or constructor injection) and call its resource methods or send requests. This keeps authentication, base URL, and Saloon middleware consistent.
• Strategy-based auth – choose a token strategy for simple PAT/CI use, and the GitHub App strategy for organisation-level automation (webhooks, bots, multi-repo access). The app strategy signs a JWT with your private key, exchanges it for a short-lived installation token, and authenticates subsequent requests.
• Cache installation tokens – GitHub App installation tokens expire after about an hour. Cache them (e.g. via Cache::remember) and let the strategy refresh on expiry; don't fetch a new token on every request.
• Handle webhooks separately – verify GitHub webhook signatures in a dedicated controller or middleware, then dispatch queued jobs that resolve the connector for follow-up API calls (commenting, labelling, etc.).
• Test with Saloon's mocking – use MockClient / Saloon::fake() to stub GitHub responses. Assert that the connector used the correct auth strategy and that error handling surfaces useful messages.
• Paginate and respect rate limits – use GitHub's Link headers and checkpoint responses; wrap calls in retry/backoff logic for secondary rate limits, especially on background jobs.

Gotchas and Tips

• Private key formatting – PEM keys stored in .env often lose newlines. Store the key with literal \n and convert in config, or mount a file. Invalid key formatting is a common cause of JWT signing failures.
• Installation token expiry – if you see sporadic 401s after long-running processes, it's likely an expired installation token. Rely on the strategy's caching/refresh rather than capturing the token once.
• Permissions are on the GitHub App – even with valid auth, 403s usually mean the app lacks the required repository permissions or the installation doesn't cover the repo. Check the app settings, not just the code.
• Laravel 13 and PHP versions – v3.1.0 targets Laravel 13; confirm your PHP version meets its requirements. If you're on Laravel 11/12, pin an earlier package release.
• Saloon 4.3 + php-jwt 7 – these are current major/minor lines. If you have your own Saloon plugins or JWT handling, check for API changes (especially around JWT::encode/decode signatures in php-jwt v7).
• Auth status debugging – use the connector's authentication status method (fixed in v3.1.0) to confirm whether a strategy has successfully authenticated before sending requests. This is the fastest way to distinguish auth misconfiguration from API errors.
• Error guidance for strategies – the new release improves error messages for strategy-based auth; read them carefully — they often point directly at the missing env var or invalid credential.
• Extension points – custom authentication strategies, connector middleware, and request classes are the intended extension points. Prefer adding a strategy over overriding the connector when you need different auth flows (e.g. GitHub Enterprise).