Sync
Synchronize repositories between Coregit and GitHub/GitLab — import, export, and auto-sync.
Overview
Sync connects a Coregit repository to an external GitHub or GitLab repository. It supports:
- Import — pull changes from GitHub/GitLab into Coregit
- Export — push changes from Coregit to GitHub/GitLab
- Auto-sync — automatically trigger sync on push events via webhooks
Sync requires a connection with a valid provider token.
Create Sync Config
Link a Coregit repo to an external repository.
POST /v1/repos/:slug/sync/config
POST /v1/repos/:namespace/:slug/sync/configPermission: Master API key only.
{
"connection_id": "conn_abc123",
"remote": "octocat/my-repo",
"direction": "import",
"branch": "main",
"auto_sync": true
}Fields
| Field | Required | Description |
|---|---|---|
connection_id | Yes | ID of an existing connection |
remote | Yes | owner/repo (GitHub) or group/project (GitLab) |
direction | No | "import" (default) or "export" |
branch | No | Branch to sync (default: repo's default branch) |
auto_sync | No | Enable webhook-based auto-sync (default: false) |
Response 201
{
"id": "sync_xyz",
"repo_id": "repo_abc",
"connection_id": "conn_abc123",
"provider": "github",
"remote": "octocat/my-repo",
"branch": "main",
"direction": "import",
"auto_sync": true,
"webhook_id": 12345
}When auto_sync is true and direction is import, Coregit registers a push webhook on the external repository. For export, auto-sync triggers after every git push to Coregit.
Get Sync Config
GET /v1/repos/:slug/sync/config
GET /v1/repos/:namespace/:slug/sync/configPermission: Any API key.
Response 200
{
"config": {
"id": "sync_xyz",
"connection_id": "conn_abc123",
"provider": "github",
"remote": "octocat/my-repo",
"branch": "main",
"direction": "import",
"auto_sync": true,
"last_synced_sha": "7f3b...",
"last_synced_at": "2026-04-05T12:30:00Z",
"last_error": null,
"connection": {
"label": "My GitHub PAT",
"external_username": "octocat"
}
}
}Returns { "config": null } if no sync config exists.
Update Sync Config
PATCH /v1/repos/:slug/sync/config
PATCH /v1/repos/:namespace/:slug/sync/configPermission: Master API key only.
{
"direction": "export",
"auto_sync": true,
"branch": "develop",
"remote": "octocat/other-repo"
}All fields are optional.
Response 200
{ "updated": true }Delete Sync Config
DELETE /v1/repos/:slug/sync/config
DELETE /v1/repos/:namespace/:slug/sync/configPermission: Master API key only.
Response 200
{ "deleted": true }Trigger Sync
Manually trigger an import or export sync.
POST /v1/repos/:slug/sync
POST /v1/repos/:namespace/:slug/syncPermission: Master API key only.
{
"sync_id": "sync_xyz",
"branch": "main"
}Fields
| Field | Required | Description |
|---|---|---|
sync_id | Yes | Sync configuration ID |
branch | No | Target branch (default: sync config's branch) |
Response 200
{
"synced": true,
"remote_sha": "7f3b...",
"commit_sha": "a1c2...",
"files_changed": 42,
"deleted": 3,
"direction": "import"
}| Field | Description |
|---|---|
synced | true if changes were applied, false if already up to date |
remote_sha | Latest commit SHA on the remote |
commit_sha | Commit SHA created by this sync (null if no changes) |
files_changed | Number of files created or updated |
deleted | Number of files deleted |
direction | "import" or "export" |
Sync History
View past sync runs for a repository.
GET /v1/repos/:slug/sync/history
GET /v1/repos/:namespace/:slug/sync/historyPermission: Any API key.
Query Parameters
| Param | Default | Description |
|---|---|---|
limit | 20 | Max results (1–100) |
cursor | — | Pagination cursor from previous response |
Response 200
{
"runs": [
{
"id": "run_abc",
"status": "success",
"message": "Imported 15 files",
"remote_sha": "7f3b...",
"commit_sha": "a1c2...",
"started_at": "2026-04-05T12:30:00Z",
"completed_at": "2026-04-05T12:30:02Z"
}
],
"next_cursor": null
}Status values: running, success, skipped, error.
How Import Works
- Coregit downloads the latest state from GitHub/GitLab
- Compares against the last synced commit
- Creates a single commit with all changes (additions, modifications, deletions)
- Updates the sync config with the new remote SHA
How Export Works
- Coregit snapshots the current tree on the configured branch
- Diffs against the tree at
last_synced_sha - Creates blobs and commits on GitHub/GitLab via their API
- Updates the remote branch ref
For GitHub, blobs are created in parallel batches of 20. For GitLab, file actions are batched in groups of 500.
Auto-Sync
Import auto-sync
When auto_sync: true and direction: "import", Coregit registers a push webhook on the external repository. Every push to the configured branch triggers an automatic import.
Webhook signatures are verified using HMAC-SHA256 (GitHub) or token comparison (GitLab).
Export auto-sync
When auto_sync: true and direction: "export", every git push to the Coregit repository automatically triggers an export to the external provider. This happens asynchronously after the push completes.
Supported Providers
| Provider | Remote Format | Example |
|---|---|---|
| GitHub | owner/repo | strayl/coregit |
| GitLab | group/project | mygroup/myproject |
SDK Examples
// Create a connection first
const { data: conn } = await git.connections.create({
provider: "github",
label: "Sync Token",
access_token: "ghp_xxxxxxxxxxxx",
});
// Set up import sync with auto-sync
const { data: config } = await git.sync.createConfig("my-repo", {
connection_id: conn.id,
remote: "octocat/my-repo",
direction: "import",
auto_sync: true,
});
// Manual sync trigger
const { data: result } = await git.sync.trigger("my-repo", {
sync_id: config.id,
});
if (result.synced) {
console.log(`Synced ${result.files_changed} files`);
}
// Check sync history
const { data: history } = await git.sync.history("my-repo", { limit: 10 });
for (const run of history.runs) {
console.log(`${run.status}: ${run.message}`);
}
// Switch to export
await git.sync.updateConfig("my-repo", {
direction: "export",
auto_sync: true,
});
// Delete sync config
await git.sync.deleteConfig("my-repo");