Skip to main content
[ PIER ]

Repositorio Privado (GitHub App)

Despliega repos GitHub vía GitHub App — un auth, muchos repos.

Application #git#github#app#private#repository

Despliega repositorios GitHub privados (y públicos) usando una GitHub App que posees. Instala la app en tu org o repos seleccionados, pega credenciales de la app en Pier, y clona / construye / despliega cualquiera de esos repos sin deploy keys per-repo. El método auth recomendado para equipos desplegando muchos repos privados a una instancia Pier.

Desplegar con Pier

  1. 1 Abre el panel de Pier y haz clic en Add service.
  2. 2 Elige Private Repository (GitHub App) 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 GitHub App?

Despliega repositorios GitHub (privados o públicos) usando una GitHub App que controlas. Creas la app bajo tu cuenta u org, la instalas en repos específicos (u org-wide), descargas su private key, y pegas las credenciales en Pier. Pier usa la API GitHub para requestar short-lived installation access tokens en clone time — sin PATs long-lived, sin deploy keys per-repo.

Este es el pattern auth recomendado para equipos desplegando muchos repos privados a una instancia Pier. Una app autoriza cualquier número de repos; revocación es per-install o per-repo; el audit trail vive en el GitHub side.

Cómo lo despliega Pier

Proveés:

  • Una Git URL (HTTPS) para el repo target
  • App ID, Installation ID, y private key (.pem) de la GitHub App
  • Branch / tag / commit, Dockerfile path, port, env vars

En clone time, Pier signs un JWT con la private key de la app, requesta un installation access token de la API GitHub, y usa ese token para git clone sobre HTTPS. Tokens expiran en ~1 hora y Pier los refresca automáticamente.

Para push-to-deploy webhook-driven, configura el webhook URL de la app para apuntar al webhook URL Pier-generated del servicio, configura un webhook secret, y Pier verifica y actúa sobre push events.

Cuándo NO usar esta plantilla

Para 1-5 repos privados bajo cuentas personales, la plantilla más simple Deploy Key (SSH key per-repo) es más fácil. Para repos públicos, la plantilla Public Repository no necesita auth en absoluto. Para hosts non-GitHub (GitLab, Bitbucket, Gitea, …), usa Deploy Key. GitHub App es la respuesta correcta específicamente para “equipo / org con muchos repos GitHub privados y queremos una sola superficie auth.”

Características clave

Una app, muchos repos

Instala la GitHub App en tu org o per-repo. Pier usa el installation token de la app para clonar cualquier repo autorizado — sin deploy keys per-repo.

Scope org-level o repo-level

Instala en toda la org (todos los repos actuales y futuros) o elige repos específicos. Revoke per-repo o per-org en cualquier momento.

Tokens auto-rotantes

GitHub Apps generan short-lived installation access tokens. Pier requesta tokens frescos automáticamente; nada long-lived que leak.

Permisos fine-grained

La app declara exactamente lo que necesita (Contents — read). Sin acceso a Actions, secrets, organization billing o cualquier otra cosa.

Webhook redeploys included

GitHub Apps pueden suscribirse a push events en install time. Configura una vez; pushes auto-triggean redeploys Pier.

Audit trail

Cada clone se logea en el GitHub side como app installation event — útil para audits de seguridad.

Casos de uso

Org con muchos repos privados

Tu org tiene docenas de repos privados y no quieres deploy keys per-repo para cada uno. Instala una GitHub App, despliega cualquier repo vía Pier.

Descomposición monorepo polyglot

Una instancia Pier única hosting N servicios desde N repos privados separados — todos autorizados vía una app.

Continuous deploy para equipos producto

El repo de cada equipo es auto-desplegado en push a main, todos autenticados vía la misma app org-scoped.

Deployments audit-conscious

Equipos Compliance / security prefieren una sola app auditada con scope per-repo sobre un mar de SSH keys long-lived.

Reemplazando PATs

Personal Access Tokens grant acceso repo-wide tied a una cuenta humana. Apps son repo-scoped, machine-owned, short-lived tokens — estrictamente mejor.

Ejemplos de código

Crea GitHub App text 
GitHub → Settings → Developer settings → GitHub Apps → New GitHub App
  Name - pier-deployments
  Homepage URL - https://pier.example.com
  Webhook - (configuraremos vía Pier después; deja vacío por ahora)
  Permissions -
    Contents - Read-only
    Metadata - Read-only
  Subscribe to events - Push
→ Create
→ Generate a private key (descarga .pem)
→ Anota App ID y Client ID
Instala la app en tu org / repos text 
App settings → Install App → Pick your org
→ Choose - "All repositories" o "Only selected repositories"
→ Install
→ Anota el Installation ID (de URL https://github.com/settings/installations/<ID>)
Conecta a Pier text 
Pier → New service → Private Repository (GitHub App)
  Git URL - https://github.com/myorg/myrepo
  Branch - main
  App ID - 12345
  Installation ID - 67890
  Private Key - (pega contenido del .pem que descargaste)
  Dockerfile path - /Dockerfile
  Port - 3000
→ Deploy
Setup deploys webhook-driven text 
Pier service → Settings → Copy webhook URL
GitHub App → settings → Webhook URL - pégalo
Webhook secret - (Pier muestra uno para copiar)
→ Save
→ Push a main → auto-rebuild + redeploy

Comparativa

vs Plantilla Deploy Key (este catálogo) Deploy Keys son más simples para 1-5 repos privados. GitHub Apps escalan mejor a 10+ repos privados bajo una org. Apps también tienen audit trails y tokens short-lived.
vs Personal Access Token (PAT) PATs están tied a cuenta humana y grant acceso a TODOS sus repos. Apps son scoped a repos específicos y owned por tu org/cuenta separadamente. Apps son estrictamente mejor seguridad.
vs GitLab / Bitbucket / Gitea Esta plantilla es GitHub-specific. Para GitLab usa deploy tokens; para Bitbucket usa OAuth apps; para Gitea usa deploy keys.
vs Public Repository (este catálogo) Public funciona sin auth — úsalo cuando el repo es genuinamente público.

Preguntas frecuentes

¿Por qué esto es mejor que PAT?
PATs están tied a cuenta humana, grant amplio acceso, y rara vez expiran. Installation tokens de GitHub App son scoped a repos específicos, owned por la app (no una persona) y auto-rotated.
¿Dónde vive la private key en Pier?
Encriptada en la DB Pier, descifrada en request time para sign JWTs para la GitHub App API. La key misma nunca deja Pier.
¿Puedo usar una app para múltiples servicios Pier?
Sí — ese es el diseño. Una app autoriza muchos repos; crea un servicio Pier per repo, todos referenciando las mismas credenciales app.
¿Qué permisos necesita la app?
Contents — Read-only y Metadata — Read-only es suficiente para clonar. Subscribe a Push events para webhook redeploys.
¿Cómo se verifican las webhook signatures?
Pier verifica el webhook secret que configuraste en la GitHub App. Rechaza cualquier webhook sin signature válida.
¿Puedo desplegar repos públicos con esta plantilla?
Sí — una vez instalada la app, puede clonar cualquier repo autorizado, público o privado.
¿Token expiration / refresh?
Installation tokens expiran en ~1 hora. Pier requesta frescos del GitHub API antes de cada clone. Tú no gestionas esto.

Servicios relacionados

Desplegar en tu VPS

Despliega repositorios GitHub privados (y públicos) usando una GitHub App que posees. Instala la app en tu org o repos seleccionados, pega credenciales de la app en Pier, y clona / construye / despliega cualquiera de esos repos sin deploy keys per-repo. El método auth recomendado para equipos desplegando muchos repos privados a una instancia Pier.

Desplegar este servicio →