Skip to content

advanced-usage.md

Latest commit

 

History

History
89 lines (63 loc) · 3.45 KB

advanced-usage.md

File metadata and controls

89 lines (63 loc) · 3.45 KB
Raw

Authentication and errors

Personal access token

GITHUB_TOKEN=ghp_your_token_here
GH_TOKEN=

config/github-client.php copies those into token and gh_token. TokenResolver uses token, then gh_token, then the GitHub CLI.

The connector base URL is https://api.github.com. The package does not read a base URL from config.

OAuth

GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_REDIRECT_URL=
use JordanPartridge\GithubClient\Facades\GithubOAuth;

$url = GithubOAuth::getAuthorizationUrl(['repo'], $state);
$token = GithubOAuth::getAccessToken($code);

Default scopes are ['repo'] when you omit the argument. Config does not supply scopes. The package does not persist state. Pass a value you stored, and compare it on the callback.

getAccessToken() posts the code to https://github.com/login/oauth/access_token and returns the access_token string. A body without that field throws AuthenticationException.

GitHub App

GITHUB_APP_ID=
GITHUB_APP_PRIVATE_KEY=
GITHUB_APP_PRIVATE_KEY_PATH=

Github::forInstallation(int $installationId): Github reads the app id and key from config and returns an installation-authenticated client. These helpers are available from v3.1.0:

use JordanPartridge\GithubClient\Facades\Github;

$github = Github::forInstallation(12345678);
$repo = $github->getRepo('owner/repo');

Choose a repository accessible to the installation. Installation tokens are refreshed before expiry. repos()->all() calls /user/repos, an authenticated-user endpoint, not an installation-repository listing.

Github::withApp(string $appId, string $privateKey, ?int $installationId = null): Github accepts PEM contents (or base64-encoded PEM), not a key path. Supplying an installation id selects installation authentication; omitting it selects app-level JWT authentication for installation management:

$privateKey = file_get_contents($pathToPem);
$app = Github::withApp($appId, $privateKey);
$installations = $app->installations()->list();
$token = $app->installations()->createAccessToken(12345678);

$github = Github::withApp($appId, $privateKey, 12345678);
$repo = $github->getRepo('owner/repo');

installations()->list(), listAll(), get(), and createAccessToken() need an app JWT, not an installation token. With config-based forInstallation(), GITHUB_APP_PRIVATE_KEY supplies PEM contents; when it is empty, GITHUB_APP_PRIVATE_KEY_PATH supplies an absolute path or a path relative to the Laravel base directory. withApp() does not read that config or load a path itself.

Errors

Status Exception
401 JordanPartridge\GithubClient\Exceptions\AuthenticationException
403 when the body or headers say the rate limit is spent RateLimitException
403 otherwise ApiException
404 ResourceNotFoundException
422 ValidationException
429 RateLimitException
500, 502, 503, 504 NetworkException
other ApiException

There is no withRateLimiting() helper and no Github::fake(). In tests, call Github::connector()->withMockClient() with a Saloon MockClient. The mock body has to include the fields the DTO constructor reads. See tests/DocumentationExamplesTest.php.

What the config file does not do

These are not implemented. They are not in the published config.

  • A custom API base URL
  • Automatic retries
  • A prefer_github_cli switch
  • OAuth scopes from config
  • A default GitHub App installation id