GitHub connection & repos

Most GitHub problems fall into one of four buckets: Synq can't read your repos, a private repo won't import, a public repo that should need no login keeps asking you to connect, or pushes aren't triggering deployments. This page walks each one from the exact message you'll see to the fix.

Synq can reach GitHub through the managed Synq GitHub App, workspace-owned GitHub Apps, a personal token, SSH key, or the local gh identity. It also manages the webhooks that power auto-deploy. If you haven't connected yet, start with Deploy from GitHub; the connection card itself lives in Settings → Git.

Synq can't read your repositories

What it means (plain words): Synq has no usable credential for your account. Either you were never connected, or a token that used to work has expired or been revoked (you signed out of gh, rotated a personal access token, or removed the App). Synq isn't broken — it just has nothing to authenticate with.

How to fix:

1. Go to Settings → Git. For a workspace-owned App, verify its source card and make sure it lists the intended GitHub account. For a local identity, use the GitHub card to reconnect it.
2. If it does show a login but repos still won't load, press Disconnect, then Connect GitHub again to mint a fresh token.
3. On a self-hosted instance using the CLI fallback, run gh auth login in the terminal on the machine running Synq, then reload the page.

A private repo won't import

What it means: GitHub only exposes a private repo to a credential that has explicit access to it. Synq can see it only if the GitHub App is installed on that owner and includes that repo, or you've given it a personal access token with the right scope. A public-repo-only token, or an App install that skipped the repo, can't see it.

How to fix:

1. Install / re-scope the App. In Settings → Git, use Install on account on the intended workspace-owned source (or Install GitHub App for the managed App). When GitHub asks which repositories to grant, choose All repositories or make sure the private repo is selected.
2. Or add a personal access token. In the project's Source tab, paste a token into the Clone Token Override card (or set a global one in Settings → Git → GitHub clone credentials). The token must include the repo scope — public_repo alone only reaches public repos.
3. Reload the picker; the repo should now appear.

A public repo keeps asking me to connect

What it means: A public github.com repo can be read and deployed with zero credentials — Synq probes it anonymously first. That probe fails closed: if the repo doesn't come back as clearly public, Synq falls back to asking for a credential. The usual reasons are that the repo isn't actually public, the owner/repo is mistyped, or it isn't on github.com.

How to fix:

1. Open the repo in a private/incognito browser window (logged out). If you can't see it, it's private — use the private-repo fix above.
2. Double-check the owner/repo spelling. Both https://github.com/owner/repo and git@github.com:owner/repo.git forms are understood, but only github.com — GitLab and GitHub Enterprise hosts always need a credential.
3. If you just made it public, wait a minute and retry. Synq caches the "public" verdict for about ten minutes, and a transient network error during the probe makes it ask for a credential that one time.

Auto-deploy isn't triggering (webhooks not firing)

What it means: Auto-deploy is a webhook — GitHub sends Synq a message the instant you push. If the message never arrives, is rejected, or arrives for a branch/project that isn't set to auto-deploy, nothing happens. Work through the checks below in order.

How to fix:

1. Turn auto-deploy on. Open the project's Source tab. If the Auto Deploy card says Disabled ("Deployments must be started manually"), toggle it on. This is also what registers the webhook on the repo.
2. Check the webhook is reachable. If the Source tab shows the "Enable auto-deploy" banner — "Auto-deploy needs a direct webhook endpoint. Expose this Synq API on a public URL or configure a verified webhook domain for direct delivery." — then your instance is on localhost or a private network and GitHub literally can't reach it. Put Synq behind a public URL, or pick a verified custom domain for direct delivery.
3. Push the branch you actually deploy. Synq only redeploys when the pushed branch matches the project's deploy branch. A push to any other branch is ignored (the logs read "No local auto-deploy projects matched"). Confirm the branch in the Source tab.
4. Fix a rejected signature. Red 401 deliveries with "Invalid signature", "Missing x-hub-signature-256 header", or "No webhook secret configured — signature cannot be verified" mean the hook's signing secret doesn't match. Toggle Auto Deploy off and on to re-register the webhook — that mints a fresh per-project secret on both sides.

Still stuck?