GitHub Provider Setup & Permissions

Tokomono\GitSync\Services\GitHubProvider integrates with the GitHub REST API v3 (https://api.github.com) using Bearer token authentication and API version header X-GitHub-Api-Version: 2022-11-28.

Step-by-Step: Creating a GitHub Personal Access Token in the GitHub UI

Option 1: Personal Access Token (Classic)

1. Log in to GitHub.com and click your profile avatar in the top-right corner.
2. Navigate to Settings → Developer settings (at the bottom of the left sidebar).
3. Click Personal access tokens → Tokens (classic).
4. Click Generate new token → Generate new token (classic).
5. Enter a descriptive Note (e.g., GitSync Staging PR Bot) and select an Expiration policy.
6. Under Select scopes, check:
   • repo (Full control of private repositories) — required to read branch SHA references, create new branches, read/write file contents, and open Pull Requests.
7. Click Generate token at the bottom of the page and copy the generated ghp_... token immediately.

Option 2: Fine-Grained Personal Access Token

1. Go to Settings → Developer settings → Personal access tokens → Fine-grained tokens.
2. Click Generate new token.
3. Select the Resource owner (your organization or user account).
4. Under Repository access, select Only select repositories and pick your target repository.
5. Under Permissions → Repository permissions, configure:
   • Contents: Read and write (needed for branch creation and file commits).
   • Pull requests: Read and write (needed to open Pull Requests).
   • Metadata: Read-only (automatically selected).
6. Click Generate token and copy the github_pat_... token.

Add Credentials to .env

GIT_SYNC_PROVIDER=github
GITHUB_TOKEN=ghp_your_copied_token_here
GITHUB_REPOSITORY=your-org/your-repo

Under the Hood: GitHub REST API Calls

GitHubProvider scopes all HTTP requests to https://api.github.com/repos/{owner}/{repo}/:

1. createBranch(string $sourceBranch, string $newBranch): void
   • Sends GET git/ref/heads/{sourceBranch} to fetch the current commit SHA (object.sha) of the base branch.
   • Sends POST git/refs with {"ref": "refs/heads/{newBranch}", "sha": "{sha}"} to create the new branch on GitHub.
   • Throws an Exception if the source branch does not exist or the branch name already exists.
2. commitFile(string $branch, string $filePath, string $content, string $commitMessage): void
   • Sends GET contents/{filePath}?ref={branch} to check whether the file already exists on the branch and retrieve its current blob sha (required by GitHub when updating an existing file).
   • Sends PUT contents/{filePath} with base64_encode($content), message, branch, and optional sha.
3. createPullRequest(string $sourceBranch, string $targetBranch, string $title, string $description): string
   • Sends POST pulls with title, head ($sourceBranch), base ($targetBranch), and body ($description).
   • Returns the html_url of the newly created GitHub Pull Request (e.g. https://github.com/your-org/your-repo/pull/42).