# Git authentication for private repos
URL: https://synquic.tech/docs/guides/git-authentication.md

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.

import { Step, Steps } from 'fumadocs-ui/components/steps';

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.

<Callout title="You usually don't have to think about this">
With your own [GitHub App](/docs/guides/self-hosted-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.
</Callout>

<Callout title="GitLab, Bitbucket, Gitea and other Git URL projects" type="info">
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](/docs/guides/deploy-from-git-url).
</Callout>

## 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.

<Callout title="Why the order looks like this" type="info">
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.
</Callout>

## How to turn each one on

<Steps>

<Step>
### 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:

```bash
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_ed25519
```

Synq 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.
</Step>

<Step>
### 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.
</Step>

<Step>
### 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.
</Step>

<Step>
### 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.
</Step>

</Steps>

## Local vs server builds

- **Local build** (build on the Synq host, transfer the output): the host's `gh` token 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 `gh` token isn't accepted as a shippable remote credential.

<Callout title="Using your own GitHub App">
With a [self-hosted GitHub App](/docs/guides/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.
</Callout>

## Related guides

<Cards>
  <Card title="Deploy from GitHub" href="/docs/guides/deploy-from-github" description="Link a repo and ship it, public or private." />
  <Card title="Custom servers" href="/docs/guides/custom-servers" description="Add your own server and set its GitHub authentication." />
  <Card title="GitHub troubleshooting" href="/docs/troubleshooting/github" description="Fix 'can't authenticate the clone' and related errors." />
</Cards>