Git authentication for private repos
How Synq authenticates the git clone when it builds your app: the server's own git, per-server tokens and SSH keys, clone tokens and GitHub Apps, and public repos.
When Synq builds your app it has to clone your repository first. For a public repo that's free: no credentials needed. For a private repo, something has to prove it's allowed to read the code. This page explains every way that can happen, in the order Synq tries them, and how to turn each one on.
You usually don't have to think about this
With your own GitHub App connected, installation tokens cover most clones. This page is for the cases where a build says it can't authenticate the clone, almost always a private repo deploying to your own server.
GitLab, Bitbucket, Gitea and other Git URL projects
This page is about GitHub repositories. A project imported with the Git URL tab does not use this chain at all: every clone uses exactly the access method saved on the project (public, its encrypted token, or its own SSH deploy key with a pinned host key), and your GitHub credentials are never sent to another host. See Deploy from any Git URL.
First, where does the clone run?
The single most important thing to understand: a credential that works on the Synq host doesn't automatically work on a remote build server. Synq can clone in two places:
- On this host (the Synq control plane), which then transfers the built output to wherever the app runs.
- On the build server itself: the server clones directly, no upload. Best for big repos, and required for bare/Direct deploys.
A token that lives on the Synq host has to be shipped to the server to clone there, and Synq is deliberately careful about which credentials it will ship. That's why the answer to "how do I auth a private clone" depends on where the clone runs.
The credential chain (server builds)
For a build that runs off this host, Synq tries these in order and uses the first one that works. Each is independent: a step is skipped when it doesn't apply, so the order only decides who wins when several are available.
| # | Credential | What it is | Ships a secret to the server? |
|---|---|---|---|
| 1 | The server's own git | gh/credential-helper/SSH key already on the box | No: resolved locally on the server |
| 2 | Per-server token or SSH key | A GitHub token or deploy key you saved for that server | Yes, only to that one server |
| 3 | Clone token / GitHub App | A per-project or global clone token, or the App installation token | Yes, short-lived, repo-scoped |
| 4 | Public repo | No credential at all | Nothing to ship |
| 5 | Clone on Synq + transfer | Clone here, upload the source | No: the code never transits the server as a token |
If none of these produce a credential for a private repo, the build stops with an actionable message instead of hanging.
Why the order looks like this
It's ranked by how little secret material moves. The server's own git (1) ships nothing, so it wins first. A stored token or key (2–3) does travel to the server, so it's used only when nothing ambient works. Cloning here and transferring the source (5) is the last resort that keeps every credential on this host.
How to turn each one on
Use the server's own git
If the build server is already logged in to GitHub, Synq uses that, with no configuration in Synq at all. On the server, any one of:
gh auth login # GitHub CLI on the box
# or a credential helper:
git config --global credential.helper store
# or an SSH key on the account:
ls ~/.ssh/id_ed25519Synq verifies the server can actually reach your repo before relying on this, so a box logged in as the wrong account is skipped rather than failing mid-build.
Save a token or SSH key on the server
On the Servers page, open a server's GitHub authentication and add a device-flow token, a personal access token, or an SSH deploy key. That credential is used for clones that run on that server. Use this when the server has no ambient git, for example a headless CI box.
Set a clone token (global or per-project)
Settings → Tokens → GitHub clone credentials stores a personal access token (classic ghp_… or fine-grained github_pat_…) used to clone private repos when the GitHub App isn't installed. Toggle Use as default clone token to put it in the chain. A per-project override (project → clone token) takes precedence over the global one for that project.
Give a classic token the repo scope, or a fine-grained token read access to the repos you deploy.
Public repos need nothing
A public GitHub repo clones anonymously: no token, exactly like a public deploy on any platform. Synq confirms this by attempting the clone from the machine that will build, so a rate-limited API check never mislabels a public repo as private.
Local vs server builds
- Local build (build on the Synq host, transfer the output): the host's
ghtoken is used directly and never leaves the host. - Server build (build on the target): a broad host token is never put into a clone URL and shipped off-host. That's why a plain
ghtoken isn't accepted as a shippable remote credential.
Using your own GitHub App
With a self-hosted GitHub App installed on the repository's owner, builds authenticate with a short-lived installation token instead of your personal identity, on the server as well as locally.
Related guides
Docker disk usage and cleanup
See what fills a server's disk (images, containers, volumes and build cache, with the project each belongs to), clean it up safely from the server's Docker tab, and schedule the cleanup so it runs by itself.
Self-hosted GitHub Apps
Create and manage workspace-owned GitHub Apps for private repositories, direct webhooks, and short-lived clone tokens.