Private Repository (SSH Deploy Key)

Deploy from a private Git repo via SSH deploy key — read-only, scoped to one repo.

Application #git#ssh#private#deploy-key#repository

Deploy from a private Git repository using an SSH deploy key. You generate a keypair, register the public half as a deploy key on the repo, paste the private half into Pier — Pier clones over SSH, builds the Dockerfile, and runs the container. The recommended auth method for private repos when you want repo-scoped, revocable, read-only access.

Deploy with Pier

1 Open the Pier dashboard and click Add service.
2 Pick Private Repository (Deploy Key) from the template list.
3 Choose the version, set a service name, and Pier provisions the container, storage, and ports automatically.
4 Attach a domain if you want HTTPS. Traefik auto-provisions the Let's Encrypt certificate.

What is the Private Repository (Deploy Key) template?

Deploy a private Git repository to Pier using an SSH deploy key — a keypair scoped to a single repository on the Git host. You generate the keypair locally, register the public key as a deploy key on your repo’s settings (read-only is fine), and paste the private key into Pier when creating the service. Pier clones the repo over SSH, builds the Dockerfile, runs the container.

Compared to using a personal access token (PAT) or SSH user key, per-repo deploy keys are strictly better — narrowly scoped, independently revocable, and a leak compromises only that one repo, not your entire account.

How Pier deploys it

You provide:

A Git SSH URL (e.g. [email protected]:myorg/myrepo.git)
A branch (or tag / commit SHA)
The SSH private key for the deploy keypair
The Dockerfile path and container port

Pier stores the private key encrypted in its database, decrypts only at clone time, performs a shallow git clone over SSH, runs docker buildx build, and starts the container. BuildKit cache + Traefik HTTPS work the same as other Git/Dockerfile templates.

Generate a webhook URL from the service settings and add it to your Git host (the webhook is plain HTTP POST and doesn’t need SSH auth) for push-to-deploy.

When NOT to use this template

If the repo is public, use the Public Repository template — no key needed. If you have many private repos under one org and want a single auth surface, GitHub App auth (the next template) scales better. For non-Dockerfile auto-build, use Railpack pointed at the Git URL. For prebuilt images, use Docker Image. Deploy Key is the right answer for a small number of private repos where per-repo scoped auth matters.

Key features

Repo-scoped access

Deploy keys are scoped to ONE repo (on GitHub) or one project (on GitLab). Compromise affects only that repo, not your whole account.

Read-only by default

Deploy keys can be added as read-only — Pier only needs to clone, not push.

Works with any Git host

GitHub, GitLab, Bitbucket, Gitea, Forgejo, sourcehut — anywhere with SSH access and deploy-key support.

Per-service keypairs

Generate a fresh keypair per Pier service. Each is independently revocable from the Git host.

Dockerfile-driven build

Same build engine as the Public Repository template — Dockerfile + BuildKit + Traefik HTTPS.

Webhook redeploys

Add the Pier webhook URL to your Git host; pushes trigger redeploys.

Use cases

Private application code

Your private app's main repo on a Git host. Pier clones via SSH, builds, ships.

Customer / client projects

A repo for a client project shouldn't have access to your other repos. Deploy key isolates it.

Forks / private mirrors

A private fork of an upstream project — deploy key gives Pier read-only access without touching your account-wide tokens.

Multi-repo monorepo decomposition

A single Pier instance with N services, each pointed at a different private repo, each with its own deploy key.

Audit-friendly

Per-service keys mean revocation is granular — fire the contractor, delete the key, done.

Code examples

Generate a deploy key (ed25519) bash

ssh-keygen -t ed25519 -C "pier-deploy-myrepo" -f ~/.ssh/myrepo_deploy
# Files: ~/.ssh/myrepo_deploy (private), ~/.ssh/myrepo_deploy.pub (public)

Repo → Settings → Deploy keys → Add deploy key
  Title: pier-deploy
  Key: (paste contents of myrepo_deploy.pub)
  ✔ Allow read-only (the default; don't grant write unless needed)
→ Add

Paste private key into Pier text

Pier → Create service → Private Repository (Deploy Key)
  Git URL (SSH): [email protected]:myorg/myrepo.git
  Branch: main
  Private key: (paste contents of ~/.ssh/myrepo_deploy)
  Dockerfile path: /Dockerfile
  Port: 3000
→ Deploy

Rotate the key (revoke + regenerate) bash

# 1. Generate new keypair
ssh-keygen -t ed25519 -f ~/.ssh/myrepo_deploy_v2

# 2. Add new public key on GitHub, delete old one.
# 3. Update Pier service's private key, redeploy.
# 4. Old key is dead; only the new one works.

How it compares

vs Public Repository template (this catalog)	Use Public for repos that are actually public — no auth needed. Use Deploy Key for private repos.
vs GitHub App template (this catalog)	GitHub App auth scales better across many private repos under one org (one app authorizes multiple repos). Deploy Key is per-repo. For a few private repos, Deploy Key is simpler.
vs Personal Access Token (PAT) over HTTPS	PATs work but auth via PATs gives Pier access to ALL your private repos. Deploy Keys are scoped to one repo — strictly better security.
vs GitLab Project Access Tokens	GitLab's PATs at the project level are like deploy keys in scope. Either auth method works on Pier; SSH deploy keys are more universal.

Frequently asked questions

ed25519 or RSA?

Always ed25519 if your Git host supports it (GitHub, GitLab, Bitbucket all do). Smaller, faster, better security than RSA.

Where does the private key live?

Encrypted in Pier's database, decrypted only at clone time. It never appears in logs or exports.

Can the key be read-write?

Yes if you grant write on the Git host side, but Pier only needs read. Default to read-only.

What if I lose the private key in Pier?

Rotate — generate a new keypair, register the new public key, update Pier's stored private key, delete the old public key from the Git host.

Per-deploy or shared keypairs?

Per-deploy. Each Pier service should have its own keypair. Don't reuse keys across services.

Bot / system account deploy keys?

GitHub also allows machine-user PATs for multi-repo access. For a small number of private repos, per-repo deploy keys are simpler.

How are webhooks set up?

Same flow as Public Repository — Pier generates a webhook URL, you paste it into the Git host's repo settings. The webhook itself doesn't need SSH auth.

Related services

Deploy on your VPS

Deploy this service →