codesync-github-integration
Deep guide on GitHub Git Trees REST API, batched GraphQL sync queries, authentic ISO 8601 timestamps, rate limiting, and zero-client-secret OAuth.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- codesync-github-integration
- description
- Deep guide on GitHub Git Trees REST API, batched GraphQL sync queries, authentic ISO 8601 timestamps, rate limiting, and zero-client-secret OAuth.
03 SKILL.md 正文
CodeSync GitHub API & Git Trees Integration Guide
Use this skill when modifying GitHub API communication, commit generation, branch updating, or OAuth authentication in src/github/.
1. Atomic Multi-File Commits via Git Trees API
CodeSync never uses the single-file Contents API (PUT /repos/contents). Instead, it uses the low-level Git Data API to execute atomic multi-file commits:
sequenceDiagram
participant Queue as CommitQueue
participant GH as GitHubClient
participant API as GitHub REST API
Queue->>GH: commitTree(repo, payload, options)
GH->>API: POST /repos/{owner}/{repo}/git/trees<br/>(base_tree + files array)
API-->>GH: tree_sha
GH->>API: POST /repos/{owner}/{repo}/git/commits<br/>(tree_sha, parents, explicit author/committer dates)
API-->>GH: new_commit_sha
GH->>API: PATCH /repos/{owner}/{repo}/git/refs/heads/{branch}<br/>(sha: new_commit_sha)
API-->>GH: 200 OK (ref updated)
GH-->>Queue: success
Git Tree Payload Construction
const tree = files.map((file) => ({
path: file.path,
mode: '100644', // Standard file mode
type: 'blob',
content: file.content, // Inline content (< 100 KB) avoids creating separate blobs
}));
const treeRes = await this.request<{ sha: string }>(
`/repos/${owner}/${repo}/git/trees`,
{
method: 'POST',
body: JSON.stringify({ base_tree: baseTreeSha, tree }),
}
);
2. Authentic Historical Timestamps Invariant
To accurately populate the user's GitHub contribution graph for historical solves, BOTH author.date and committer.date must be explicitly defined using the original solve timestamp:
const isoDate = new Date(submission.timestamp).toISOString();
const commitPayload = {
message: `[CodeSync] Solved: ${submission.problem.title} (${submission.language})`,
tree: treeSha,
parents: [parentCommitSha],
author: {
name: user.name || user.login,
email: user.email || `${user.login}@users.noreply.github.com`,
date: isoDate, // Explicit ISO 8601
},
committer: {
name: user.name || user.login,
email: user.email || `${user.login}@users.noreply.github.com`,
date: isoDate, // Must match author.date
},
};
3. High-Performance Batched GraphQL Sync Context
Rather than making 5 separate REST calls to retrieve the branch reference, parent commit SHA, base tree SHA, README.md, and stats.json, GitHubClient.fetchSyncContext() combines everything into a single GraphQL query:
query getSyncContext($owner: String!, $name: String!, $branch: String!) {
repository(owner: $owner, name: $name) {
ref(qualifiedName: $branch) {
target {
oid
... on Commit {
tree {
oid
}
}
}
}
readme: object(expression: "HEAD:README.md") {
... on Blob { text }
}
stats: object(expression: "HEAD:stats.json") {
... on Blob { text }
}
}
}
Note: If the GraphQL endpoint returns errors (e.g. empty repository or missing scopes), the client transparently falls back to individual REST requests.
4. Chained Commit SHAs & Race Condition Mitigation
When syncing multiple queued submissions sequentially, GitHub's internal database replicas experience brief propagation delays. Reading the head ref immediately after a commit often returns the old SHA, leading to HTTP 409 fast-forward conflicts.
The Solution:
CodeSync keeps the returned commit_sha in memory and passes it directly as the parentCommitSha for the next commit in the batch, completely bypassing ref polling during batch commits.
5. Zero-Client-Secret Universal OAuth Architecture
Extensions must never bundle the GitHub OAuth App Client Secret. CodeSync uses a serverless OAuth proxy (codesync-oauth deployed on Cloudflare Workers):
[Browser Extension] [GitHub OAuth] [Cloudflare OAuth Proxy]
│ │ │
│─── 1. chrome.identity ────────> │
│ (launchWebAuthFlow) │ │
│ │ │
│─── 2. User Authorizes ────────> │
│ │ │
│<── 3. Redirect with ?code ────┘ │
│ │
│─── 4. POST /token { code, state } ───────────────────────────>
│ │─── 5. POST /login/oauth/access_token
│ │ (Injects Client Secret safely)
│<── 6. Returns encrypted access_token ────────────────────────┘
6. Rate Limiting & Backoff Strategy
GitHubClient intercepts HTTP 429 and 403 rate-limit responses:
if (response.status === 429 || response.status >= 500) {
const retryAfter = response.headers.get('Retry-After');
const delayMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : (attempt + 1) * 1000;
await this.sleep(delayMs);
continue; // Retry with exponential delay
}
If primary rate limits are exhausted, x-ratelimit-reset is parsed to provide the user with the exact reset time.
04 同仓库更多 Skills
openspec-update-change
Update an OpenSpec change by revising its existing planning artifacts and keeping them coherent with one another. Use when the user wants to revise a change's plan, fold new decisions into it, or reconcile its artifacts after an edit. Never edits code.
openspec-sync-specs
Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
openspec-propose
Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
openspec-explore
Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
openspec-archive-change
Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
openspec-apply-change
Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.