docs GitHub App
GitHub App
Conecta repositorios de GitHub sin tokens de acceso, con webhooks automáticos, estados de commit y comentarios en PR.
Por qué usar la GitHub App
DeployKit puede acceder a un repositorio privado de dos formas: un token de acceso pegado en la aplicación (funciona con GitHub, GitLab, Gitea o cualquier servidor git HTTPS), o una GitHub App registrada en tu instancia. Para github.com la App es el camino recomendado:
- No se almacena ningún token de larga duración: cada clonado usa un token de instalación que caduca tras una hora y solo ve los repositorios a los que diste acceso
- Eliges cuenta → repositorio → rama desde una lista en lugar de pegar una URL
- Los push y los pull requests llegan automáticamente: no hay que configurar ningún webhook por repositorio
- Los repositorios se identifican por su id numérico de GitHub, así que renombrar o transferir un repo no rompe el auto-despliegue
- Cada despliegue se reporta en el commit como un estado, y los despliegues de preview comentan su URL en el pull request
Ambos caminos pueden coexistir: las aplicaciones que no están conectadas siguen usando su token de acceso y el webhook del repositorio.
Antes de empezar — WEB_URL debe ser pública: la URL del webhook de la App (<WEB_URL>/api/webhooks/github) y la URL de redirección (<WEB_URL>/settings/github/callback) se construyen a partir de WEB_URL, nunca a partir de la cabecera Host de la petición. El registro falla si WEB_URL no está definida o apunta a localhost / una dirección privada. El compose de producción la deriva como https://${DOMAIN}; para desarrollo local, apúntala a un túnel (cloudflared, ngrok). Ambas URLs quedan fijadas en la App cuando se crea: si más tarde cambias DOMAIN, desconecta y registra la App de nuevo, o edita sus URLs en GitHub.
Registrar la App
Cada instancia de DeployKit tiene su propia App privada (GitHub debe entregar los webhooks a tu servidor, así que no hay una App central compartida). El registro usa el flujo de manifest de GitHub: nunca copias a mano un App ID ni una clave privada. Se requiere el rol Admin.
- Ve a Settings → GitHub App y haz clic en Set up (o abre /settings/github)
- Opcionalmente indica un nombre para la App (por defecto: "DeployKit - <your host>"; los nombres de App son únicos en todo GitHub) y una Organization donde crearla; déjalo vacío para tu cuenta personal. Crearla en una organización requiere permisos de propietario en ella
- Haz clic en Register on GitHub y confirma la creación en GitHub
- GitHub redirige de vuelta a DeployKit, que intercambia el código de un solo uso por las credenciales de la App y las guarda cifradas
- Haz clic en Install the App y elige la cuenta u organización propietaria de tus repositorios
¿Ya creaste una App manualmente? Despliega Already created an App? Connect it manually y pega su App ID, la clave privada (.pem) y el secreto del webhook. DeployKit verifica las credenciales contra GitHub antes de guardarlas. La URL del webhook de la App debe apuntar a esta instancia y necesita los permisos que se listan más abajo.
Instalaciones y acceso a repositorios
La página de la GitHub App lista cada cuenta donde está instalada la App, indica si tiene acceso a todos los repositorios o solo a algunos seleccionados, y marca las instalaciones suspendidas. Desde ahí puedes:
- Install on an account — instalar la App en otro usuario u organización
- Configure — abrir GitHub para cambiar qué repositorios puede ver la instalación
- Test connection — verificar que las credenciales guardadas siguen funcionando
- Refresh installations — resincronizar la lista de instalaciones desde GitHub
- Disconnect — quitar la App de DeployKit (la App en sí permanece en GitHub)
Instalar, desinstalar y cambiar la selección de repositorios en GitHub se detecta automáticamente mediante eventos de webhook. Es preferible conceder acceso a repositorios seleccionados en lugar de a todos: limita lo que puede alcanzar la clave privada de la App.
Conectar una aplicación
Al crear una aplicación, o desde General → Source en una existente (Connect through the GitHub App instead), elige la cuenta, el repositorio y la rama en las listas. Una aplicación conectada muestra una insignia GitHub App y ningún campo de token de acceso. Listar instalaciones y repositorios requiere el rol de operador en el proyecto.
Auto-despliegue
La App se suscribe a push y a pull_request. Un push despliega todas las aplicaciones conectadas cuyo repositorio y rama coincidan; la coincidencia usa la instalación más el id numérico del repositorio en GitHub, nunca la URL. Si el repositorio aún tiene un webhook antiguo creado a mano, su entrega duplicada se ignora para las aplicaciones conectadas, así que un push nunca despliega dos veces, pero puedes borrar ese webhook sin problema. Consulta Webhooks & CI/CD.
Estados de commit
Para las aplicaciones conectadas, DeployKit publica un estado de commit de GitHub en el commit desplegado, tanto para despliegues lanzados por webhook como manuales:
- pending — cuando el despliegue está en cola y mientras se hace el build
- success — cuando el nuevo contenedor está saludable
- failure — cuando falla cualquier paso
El contexto del estado es deploykit/<app name> y su enlace abre la aplicación en tu panel, así que puedes usarlo como check obligatorio en la protección de ramas. Los despliegues de preview reportan bajo el contexto de su aplicación padre, de modo que la protección de ramas ve un único check estable por aplicación. Los estados son best-effort: si GitHub no es accesible, el despliegue sigue completándose con éxito. Vienen activados por defecto; establece commitStatusEnabled: false mediante la API application.update para desactivarlos en una aplicación concreta.
Despliegues de preview y comentarios en PR
Con los despliegues de preview activados en una aplicación conectada, cada pull request obtiene su propio entorno y DeployKit mantiene un único comentario en el PR: "Deploying preview", luego "Preview ready" con la URL (o "Preview failed") y un enlace a los logs del despliegue, y por último "Preview removed" cuando se cierra el PR. Los redespliegues editan el mismo comentario en lugar de publicar nuevos. Las previews heredan la conexión de App de su aplicación padre, así que no almacenan credenciales propias.
Permisos
La App solo solicita lo que estas funciones necesitan:
| Permiso | Acceso | Se usa para |
|---|---|---|
| Metadata | Lectura | Listar repositorios y ramas |
| Contents | Lectura | Clonar repositorios privados |
| Commit statuses | Escritura | Reportar los resultados del despliegue |
| Pull requests | Escritura | Publicar el comentario de preview |
Nunca solicita permisos de checks, workflows, administración ni issues.
Desconectar y desinstalar
- Desconectar la App en DeployKit deja a las aplicaciones conectadas sin credenciales hasta que vuelvas a conectarla o les des un token de acceso; se te pide confirmación si alguna aplicación la usa
- Desinstalar la App de una cuenta en GitHub nunca elimina aplicaciones: pasan a estar desconectadas y recurren a su token de acceso, o fallan con un error claro
- La App nunca se incluye en una exportación de configuración: está ligada a la URL del webhook de esta instancia. Al importar, las aplicaciones se vuelven a vincular a la instalación local que puede ver su repositorio