GitHub

The GitHub API connects an Synq instance to GitHub — via the Synq GitHub App, an OAuth account, or the local gh CLI — and then lets you browse the accounts, repositories, branches and files you can deploy from. It also manages the push webhooks that drive auto-deploy. In the dashboard this is the GitHub connection card in Settings and the repo picker in the deploy wizard.

Connection state

GET /api/github/home is the dashboard's single entry point: it returns { state, accounts, repos } in one round trip, filtered to the accounts and repos your member role is allowed to see. GET /api/github/status is narrower — the Settings card's data source — returning { state, accounts, installUrl, cloudUnreachable, customSourcesConfigured }. The last field tells clients that App lifecycle controls belong to the workspace source manager rather than the legacy Synq App connection.

const result = await ship.github.getHome();
console.log(result);

curl "$SYNQ_URL/api/github/home" \
  -H "Authorization: Bearer $SYNQ_TOKEN"

Connect

Starts or advances the connection flow. The response is intentionally mode-agnostic — the frontend just reacts to the flow field:

• { connected: true } — already connected, nothing to do.
• { connected: false, flow: "redirect", url } — open url (OAuth handoff or GitHub App install).
• { connected: false, flow: "device_code", userCode, verificationUri, ... } — self-hosted device login.
• { connected: false, flow: "terminal", command, message } — run command (e.g. gh auth login) yourself.

The optional body field source ("oauth" | "cli") forces a specific path when the dashboard shows both the "Connect Synq App" and "Use gh CLI" buttons; omit it to let the server pick based on the instance's auth mode.

const result = await ship.github.connect({
  source: "oauth",
});
console.log(result);

curl -X POST "$SYNQ_URL/api/github/connect" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source":"oauth"}'

Disconnect

POST /api/github/disconnect

Body (or ?source=): source is "oauth", "cli", or "all" (default "all"). This drops Synq's stored credentials for that source; it does not uninstall the GitHub App — that happens only when you remove it from github.com (Synq reacts to the uninstall webhook).

This endpoint does not delete a workspace-owned source. Use DELETE /api/github/sources/:id for that explicit owner-only operation.

Workspace-owned GitHub App sources

These endpoints are available only on self-hosted instances. All reads are sanitized: private keys, client secrets, webhook secrets, and their encrypted envelope are never returned.

List sources

Returns { data, configuration }. configuration contains publicReady, publicUrl, setupUrl, and webhookUrl. Each source in data contains public App metadata, health, default status, and its claimed installations.

One-click manifest

Start the GitHub.com flow with:

The response contains { url, manifest }. Submit manifest as a JSON string in a form field named manifest to url; the dashboard does this automatically. GitHub redirects to the configured setup page with code and state, which must be sent to:

POST /api/github/sources/manifest/convert
{ "code": "…", "state": "…" }

Conversion consumes the user/workspace-bound state exactly once, encrypts GitHub's generated credentials, and returns { data, installUrl }.

Manual registration and GitHub Enterprise Server

POST /api/github/sources/manual

The API signs an App JWT and verifies /app before saving the source. It returns { data, installUrl }.

PATCH /api/github/sources/:id accepts the same identity and endpoint fields, all optional. Omitted secret fields retain their existing encrypted values. App ID or API URL cannot change while the source has claimed installations. POST .../verify refreshes public App metadata and marks bad credentials as needing attention.

Making a source default atomically rebinds existing projects for every GitHub owner installed on that source. Deleting a source promotes another active source when possible and rebinds affected projects; projects with no replacement lose their installation binding and auto-deploy is disabled. Deleting locally does not uninstall the GitHub App itself.

Create a repository

const result = await ship.github.createRepo({
  name: "my-app",
  private: true,
  owner: "acme",
});
console.log(result);

curl -X POST "$SYNQ_URL/api/github/repos" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-app","private":true,"owner":"acme"}'

Returns 201 with { data } (the created repository).

Browse repos, branches and files

List repos for the connected account (?owner= narrows to one account), or for a named org via GET /api/github/orgs/:org/repos. Both return { data: [...] } filtered to repos your role may see.

File browsing reads directly from GitHub:

• GET /api/github/repos/:owner/:repo/files — directory listing. Query: path (default repo root) and branch.
• GET /api/github/repos/:owner/:repo/file — one file's contents. Query: file (default package.json) and branch. .json files are parsed and returned as JSON.

const result = await ship.github.getFile({
  owner: "acme",
  repo: "my-app",
  file: "package.json",
  branch: "main",
});
console.log(result);

curl "$SYNQ_URL/api/github/repos/acme/my-app/file?file=package.json&branch=main" \
  -H "Authorization: Bearer $SYNQ_TOKEN"

Webhooks

POST /api/github/repos/:owner/:repo/webhooks registers the Synq push webhook on the repo (or reuses an existing one) so pushes trigger auto-deploy. It takes no request body — the target repo comes from the path. GET lists the repo's hooks. To remove one, DELETE with the hook id:

DELETE /api/github/repos/:owner/:repo/webhooks

Clone token

GET /api/github/repos/:owner/:repo/clone-token mints a short-lived (under an hour) GitHub App installation token and returns { token, cloneUrl, command } — a ready-to-run git clone. This is the same credential the build pipeline clones with, and is available only when the Synq GitHub App is installed for the owner.

Errors

An instance configured with its own self-hosted GitHub App does not use this cloud proxy; GITHUB_AUTH_MODE=auto selects the complete local App configuration first.

Operations

Connect

Repositories and source

Webhooks

GitHub App sources

HTTP endpoints