Skip to main content
[ PIER ]

Repositorio Privado (SSH Deploy Key)

Despliega desde repo Git privado vía SSH deploy key — repo-scoped, read-only.

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

Despliega desde un repositorio Git privado usando una SSH deploy key. Generas un keypair, registras la mitad pública como deploy key en el repo, pegas la mitad privada en Pier — Pier clona sobre SSH, construye el Dockerfile y corre el contenedor. El método auth recomendado para repos privados cuando quieres acceso repo-scoped, revocable, read-only.

Desplegar con Pier

  1. 1 Abre el panel de Pier y haz clic en Add service.
  2. 2 Elige Private Repository (Deploy Key) en la lista de plantillas.
  3. 3 Elige la versión, asigna un nombre al servicio y Pier provisionará automáticamente el contenedor, el almacenamiento y los puertos.
  4. 4 Vincula un dominio si quieres HTTPS. Traefik genera el certificado de Let's Encrypt automáticamente.

¿Qué es la plantilla Private Repository (Deploy Key)?

Despliega un repositorio Git privado a Pier usando una SSH deploy key — un keypair scoped a un solo repositorio en el Git host. Generas el keypair localmente, registras la clave pública como deploy key en los settings de tu repo (read-only está bien), y pegas la private key en Pier cuando creas el servicio. Pier clona el repo sobre SSH, construye el Dockerfile, corre el contenedor.

Comparado a usar un personal access token (PAT) o SSH user key, deploy keys per-repo son estrictamente mejores — narrowly scoped, independientemente revocables, y un leak compromete solo ese repo único, no tu cuenta entera.

Cómo lo despliega Pier

Proveés:

  • Un Git SSH URL (e.g. [email protected]:myorg/myrepo.git)
  • Un branch (o tag / commit SHA)
  • La SSH private key para el deploy keypair
  • El path del Dockerfile y puerto del contenedor

Pier almacena la private key encriptada en su DB, descifra solo en clone time, realiza un shallow git clone sobre SSH, corre docker buildx build y arranca el contenedor. Caché BuildKit + Traefik HTTPS funcionan igual que otras plantillas Git/Dockerfile.

Genera un webhook URL desde service settings y agrégalo a tu Git host (el webhook es plain HTTP POST y no necesita SSH auth) para push-to-deploy.

Cuándo NO usar esta plantilla

Si el repo es público, usa la plantilla Public Repository — sin key necesaria. Si tienes muchos repos privados bajo una org y quieres una sola superficie auth, GitHub App auth (la siguiente plantilla) escala mejor. Para auto-build non-Dockerfile, usa Railpack apuntado al Git URL. Para imágenes prebuilt, usa Docker Image. Deploy Key es la respuesta correcta para un pequeño número de repos privados donde auth scoped per-repo importa.

Características clave

Acceso repo-scoped

Deploy keys son scoped a UN repo (en GitHub) o un proyecto (en GitLab). Compromise afecta solo ese repo, no toda tu cuenta.

Read-only por defecto

Deploy keys pueden agregarse como read-only — Pier solo necesita clonar, no pushear.

Funciona con cualquier host Git

GitHub, GitLab, Bitbucket, Gitea, Forgejo, sourcehut — donde sea con SSH access y soporte deploy-key.

Keypairs per-servicio

Genera un keypair fresco per Pier service. Cada uno independientemente revocable desde el Git host.

Build driven por Dockerfile

Mismo engine de build que la plantilla Public Repository — Dockerfile + BuildKit + Traefik HTTPS.

Webhook redeploys

Agrega el Pier webhook URL a tu Git host; pushes triggean redeploys.

Casos de uso

Código de aplicación privado

El repo principal de tu app privada en un Git host. Pier clona vía SSH, construye, ship.

Proyectos cliente / customer

Un repo para un proyecto cliente no debería tener acceso a tus otros repos. Deploy key lo aísla.

Forks / mirrors privados

Un fork privado de un proyecto upstream — deploy key le da a Pier acceso read-only sin tocar tus tokens account-wide.

Descomposición monorepo multi-repo

Una instancia Pier única con N servicios, cada uno apuntado a un repo privado diferente, cada uno con su propia deploy key.

Audit-friendly

Keys per-servicio significa revocación granular — despide al contractor, borra la key, listo.

Ejemplos de código

Genera 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)
Registra la clave pública en GitHub text 
Repo → Settings → Deploy keys → Add deploy key
  Title - pier-deploy
  Key - (pega contenido de myrepo_deploy.pub)
  ✔ Allow read-only (default; no grant write a menos que necesites)
→ Add
Pega private key en Pier text 
Pier → Create service → Private Repository (Deploy Key)
  Git URL (SSH) - [email protected]:myorg/myrepo.git
  Branch - main
  Private key - (pega contenido de ~/.ssh/myrepo_deploy)
  Dockerfile path - /Dockerfile
  Port - 3000
→ Deploy
Rota la key (revoke + regenerate) bash 
# 1. Genera nuevo keypair
ssh-keygen -t ed25519 -f ~/.ssh/myrepo_deploy_v2

# 2. Agrega nueva pub key en GitHub, borra la vieja
# 3. Actualiza private key del servicio Pier, redeploy
# 4. La key vieja está muerta; solo la nueva funciona

Comparativa

vs Plantilla Public Repository (este catálogo) Usa Public para repos que son realmente públicos — sin auth needed. Usa Deploy Key para repos privados.
vs Plantilla GitHub App (este catálogo) GitHub App auth escala mejor entre muchos repos privados bajo una org (una app autoriza múltiples repos). Deploy Key es per-repo. Para pocos repos privados, Deploy Key es más simple.
vs Personal Access Token (PAT) sobre HTTPS PATs funcionan pero auth vía PATs da a Pier acceso a TODOS tus repos privados. Deploy Keys son scoped a un repo — estrictamente mejor seguridad.
vs GitLab Project Access Tokens PATs de GitLab a nivel proyecto son como deploy keys en scope. Cualquier método auth funciona en Pier; SSH deploy keys son más universales.

Preguntas frecuentes

¿ed25519 o RSA?
Siempre ed25519 si tu Git host lo soporta (GitHub, GitLab, Bitbucket todos lo hacen). Más pequeño, más rápido, mejor seguridad que RSA.
¿Dónde vive la private key?
Encriptada en la DB de Pier, descifrada solo en clone time. Nunca aparece en logs o exports.
¿Puede ser read-write la key?
Sí si grant write en el Git host side, pero Pier solo necesita read. Default a read-only.
¿Y si pierdo la private key en Pier?
Rota — genera nuevo keypair, registra nueva pub key, actualiza private key stored de Pier, borra la pub key vieja del Git host.
¿Per-deploy o keypairs compartidos?
Per-deploy. Cada servicio Pier debería tener su propio keypair. No reuses keys entre servicios.
¿Bot / system account deploy keys?
GitHub también permite PATs de machine-user para acceso multi-repo. Para pequeño número de repos privados, deploy keys per-repo son más simples.
¿Cómo se configuran los webhooks?
Mismo flow que Public Repository — Pier genera webhook URL, pegas en settings del Git host. El webhook no necesita SSH auth.

Servicios relacionados

Desplegar en tu VPS

Despliega desde un repositorio Git privado usando una SSH deploy key. Generas un keypair, registras la mitad pública como deploy key en el repo, pegas la mitad privada en Pier — Pier clona sobre SSH, construye el Dockerfile y corre el contenedor. El método auth recomendado para repos privados cuando quieres acceso repo-scoped, revocable, read-only.

Desplegar este servicio →