Git authentication for private repos
How Openship authenticates the git clone when it builds your app — forwarding your local git identity, the server's own git, per-server tokens and SSH keys, and public repos.
When Openship 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 Openship tries them, and how to turn each one on.
You usually don't have to think about this
On Openship Cloud, connecting the GitHub App is all you need. On the desktop app, your local gh login is used automatically. 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.
First, where does the clone run?
The single most important thing to understand: a credential that works on your laptop doesn't automatically work on a remote build server. Openship can clone in two places:
- On this host (your desktop app, or the Openship control plane) — then it 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 your machine has to be shipped to the server to clone there — and Openship 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, Openship 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 | Forwarded git identity | Your local gh login, tunneled to the server over SSH for the clone only | No — vended on demand, never written to disk |
| 2 | The server's own git | gh/credential-helper/SSH key already on the box | No — resolved locally on the server |
| 3 | Per-server token or SSH key | A GitHub token or deploy key you saved for that server | Yes — only to that one server |
| 4 | Clone token / GitHub App | A per-project or global clone token, or the App installation token | Yes — short-lived, repo-scoped |
| 5 | Public repo | No credential at all | Nothing to ship |
| 6 | Clone on Openship + 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. Forwarding (1) and the server's own git (2) ship nothing — so they win first. A stored token or key (3–4) does travel to the server, so it's used only when nothing ambient works. Cloning here and transferring the source (6) is the last resort that keeps every credential on this host.
How to turn each one on
Forward your git identity (recommended on desktop)
Turn on Settings → Clone credentials → "Forward my git identity to build servers." When a build runs on a remote server, Openship forwards your local gh login over the SSH tunnel just for that clone. Nothing is written to the server, and it's gone the moment the clone finishes.
This is a single per-operator switch, not a per-deploy checkbox — set it once and every server clone uses it. It applies to the desktop app (which has your local gh and an SSH tunnel to the server); it's inert where there's no local git identity to forward.
Use the server's own git
If the build server is already logged in to GitHub, Openship uses that — no configuration in Openship 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_ed25519Openship 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 and you don't want to forward from your machine — 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, no forwarding, exactly like a public deploy on any platform. Openship 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 this machine, transfer the output): your local
ghtoken is used directly and never leaves the machine. - Server build (build on the target): a broad local token is never put into a clone URL and shipped off-host. That's exactly why forwarding (1) exists — it vends the identity over the SSH tunnel on demand instead of writing it to the server — and why a plain
ghtoken isn't accepted as a shippable remote credential.
Openship Cloud
Cloud builds run inside the Cloud workspace and authenticate with the GitHub App installation token. Connect the App from Settings → GitHub and you're done — the forwarding/server-token steps above are for self-hosted server deploys.
What next?
Connect your own server
Add one of your own machines over SSH and let Openship install everything it needs to run your apps.
Migrate from Coolify, Dokploy, or Dokku
Move an existing self-hosted server onto Openship without redeploying from scratch — Openship scans your running Docker containers and adopts them in place, with a zero-downtime path and server-to-server moves.