GitHub Adapter

Wraps the knplabs/github-api SDK. Currently focused on issues (not PRs, releases, etc.).

Part of the pocketarc/laravel-integrations-adapters package.

Setup

// config/integrations.php
'providers' => [
    'github' => \Integrations\Adapters\GitHub\GitHubProvider::class,
],

$integration = Integration::create([
    'provider' => 'github',
    'name' => 'My Repo',
    'credentials' => ['token' => 'ghp_...'],
    'metadata' => ['owner' => 'acme', 'repo' => 'widgets'],
]);

Credentials	Metadata
token (string) -- GitHub personal access token	owner (string) -- repository owner
	repo (string) -- repository name

Resources

$client = new GitHubClient($integration);

Resource	Method	Description
$client->issues()	->create($title, $body, $labels)	Create an issue. Returns GitHubIssueData.
	->get($number)	Get a single issue by number.
	->since($since, $callback)	Iterate issues updated since a timestamp. Skips PRs.
	->close($number, $stateReason)	Close an issue. Optional state reason (completed, not_planned, duplicate).
	->reopen($number)	Reopen a closed issue.
	->timeline($number, $callback)	Iterate timeline events (labels, assignments, etc.).
$client->comments()	->list($number, $callback)	Iterate all comments on an issue.
	->add($number, $body)	Add a comment to an issue. Returns ?GitHubCommentData.
$client->assets()	->download($url)	Download an asset with token auth for GitHub-hosted URLs.

All methods go through Integration::request() / requestAs() internally, so every API call is logged, health-tracked, and rate-limited.

Retry handling

The provider implements CustomizesRetry so the core handles retry for GitHub SDK exceptions (rate limits, server errors, connection failures) with method-aware defaults (GET = 3 attempts, non-GET = 1).

Sync

The adapter syncs issues via $client->issues()->since(). Each issue dispatches a GitHubIssueSynced event. Failed items dispatch GitHubIssueSyncFailed and don't advance the sync cursor past them. After the sync completes, GitHubSyncCompleted fires with the SyncResult.

First sync (null cursor) fetches all issues from timestamp 0. Set sync_cursor on the integration to control the starting point:

$integration->updateSyncCursor('2024-05-01T00:00:00+00:00');

Every sync subtracts a 1-hour buffer from the cursor to catch items updated between syncs. Consumers should use updateOrCreate() in their event listeners since overlap is expected.

Defaults: 5-minute sync interval, 60 requests/minute rate limit.

Data classes

Class	Description
GitHubIssueData	Issue with body, state, user, labels, assignees, attachments (extracted from body HTML). Stores original API response.
GitHubCommentData	Comment with body, user, attachments (extracted from body HTML). Stores original API response.
GitHubEventData	Timeline event with formatted descriptions. Handles cross-reference ID synthesis.
GitHubUserData	User with login, avatar, name, email.
GitHubAttachmentData	Attachment URL extracted from issue/comment HTML body.

Enums

Enum	Values
GitHubEventType	~50 timeline event types with human-readable descriptions.
GitHubIssueStateReason	Completed, NotPlanned, Duplicate, Reopened