Conectar GitHub

Cada instalación de Pitangus usa su propia GitHub App: la creas tú, en tu cuenta o en una organización que administres. Si necesitas varias organizaciones, configúrala para que pueda instalarse en cualquier cuenta. El panel (Integraciones) puede crearla por ti en dos clics; los pasos manuales de abajo son la alternativa.

La forma rápida: crearla desde el panel

En Integraciones → GitHub, Crear en GitHub abre el formulario de GitHub con todo ya completado (el flujo de manifiesto de GitHub): el nombre, los cuatro permisos de abajo, sin webhook ni OAuth, y la dirección de vuelta a tu panel. Si quieres, escribe la organización que será su dueña y marca Varias organizaciones si la vas a instalar en más de una cuenta. Confirmas en GitHub y vuelves al panel con la App conectada; después la instalas en tus repositorios (paso 4).

• La App es tuya: se crea en tu cuenta y GitHub le entrega su clave privada directamente a tu servidor, que la guarda cifrada. Nunca pasa por tu navegador, y los secretos de cliente y de webhook que GitHub también devuelve se descartan.
• La vuelta funciona también en 127.0.0.1: quien vuelve es tu navegador, no GitHub llamando a tu servidor, así que el panel no necesita ser accesible desde internet.
• El enlace sirve una sola vez y dura una hora; si caduca, empieza de nuevo. El nombre de la App debe ser único en GitHub: si ya existe, GitHub te deja cambiarlo en esa misma página.

Si prefieres hacerlo a mano, o el panel no llega a GitHub, sigue los pasos de abajo (el panel también los muestra, plegados en ¿Prefieres crearla a mano?).

1. Crear la App

Abre el formulario de nueva App:

• Cuenta personal: https://github.com/settings/apps/new
• Organización: https://github.com/organizations/<tu-org>/settings/apps/new

Rellena solo esto:

Campo	Valor
GitHub App name	El que quieras, p. ej. Pitangus. Tiene que ser único en todo GitHub: si ya existe, añade tu equipo.
Homepage URL	Cualquier URL tuya; p. ej. tu perfil de GitHub o la URL de tu panel.
Callback URL	Vacío.
Request user authorization (OAuth) during installation	Sin marcar.
Setup URL (opcional)	http://127.0.0.1:8766/oauth/callback (o tu URL pública + /oauth/callback) y marca Redirect on update. Tras instalarla, GitHub te devuelve al panel, que te pregunta si conectas esa cuenta: un clic.
Webhook → Active	Desmarcado. El panel consulta los PRs por su cuenta.

Repository permissions, solo estos cuatro:

Permiso	Nivel	Para qué
Contents	Read-only	Descargar el código para analizarlo.
Metadata	Read-only	Obligatorio en toda App.
Pull requests	Read and write	Leer los cambios del PR y dejar un comentario con el resultado.
Commit statuses	Read and write	Marcar el commit como aprobado o bloqueado.

Nada en Organization permissions ni en Account permissions, y ningún evento suscrito. Si más adelante la App tuviera permisos de más, el panel lo avisa en rojo.

En Where can this GitHub App be installed? elige Any account si necesitas instalarla en varias organizaciones. Para una sola cuenta puedes usar Only on this account. Después pulsa Create GitHub App.

2. App ID y clave privada

En la página de la App recién creada:

• App ID: aparece arriba, en la sección About.
• Private keys → Generate a private key: se descarga un fichero .pem.

3. Conectarla al panel

En Integraciones → GitHub, escribe el App ID, elige el .pem y pulsa Verificar y guardar. El panel firma un JWT con la clave y pregunta a GitHub por la App: si no casan, no guarda nada y te dice por qué. Si casan, guarda la clave cifrada en config/ y muestra el nombre, la cuenta y los permisos que GitHub le atribuye.

La clave no vuelve a salir del servidor. Borra el .pem de tu carpeta de descargas cuando termines.

4. Instalarla en tus repositorios

Pulsa Instalar en GitHub, elige una cuenta y Only select repositories, y marca los repositorios que quieras analizar. Repite la instalación en cada organización. De vuelta en el panel (con la Setup URL, que la App creada desde el panel ya trae, GitHub te lleva allí), pulsa Conectar en la cuenta que te ofrece, o Buscar instalaciones y Conectar cuenta en cada organización que quieras usar. Instalar la App no incorpora automáticamente las cuentas a este workspace. Los repositorios de las cuentas conectadas aparecen en Repositorios y en Nuevo análisis; allí puedes filtrar por organización.

Para añadir o quitar repositorios más tarde: Integraciones → Cambiar repositorios en la cuenta correspondiente. Para dejar de usar una organización aquí, pulsa Desconectar cuenta.

Revisión de pull requests

En Pull requests activa la vigilancia por repositorio y elige el umbral de bloqueo. Cada pocos minutos (PITANGUS_PR_POLL_SECONDS) se revisan los PRs abiertos con commits nuevos: solo cuenta lo que el PR introduce frente a la rama principal. El resultado se publica como un único comentario que se actualiza y como un estado de commit pitangus.

Alternativa: montar la App como secreto

Si prefieres no guardar la clave en el almacén (por ejemplo, porque ya usas un gestor de secretos), declara en el entorno del contenedor:

GITHUB_APP_ID=123456
GITHUB_APP_SLUG=tu-app          # el de github.com/apps/<slug>
GITHUB_APP_PRIVATE_KEY_FILE=/run/secrets/github-app.pem

El entorno manda sobre el almacén. Monta el .pem en solo lectura.

Cambiar de App

Integraciones → Usar otra GitHub App… → Olvidar la App borra del servidor la clave y la conexión. La App sigue existiendo en GitHub: bórrala allí si ya no la usas.

Problemas frecuentes

Mensaje	Qué pasa
GitHub no reconoce ese App ID con esa clave privada	La clave es de otra App, o la revocaste. Genera otra en la página de la App.
La clave privada debe ser RSA de al menos 2048 bits	Has subido otro fichero; usa el .pem que descarga GitHub.
La App todavía no está instalada en ninguna cuenta	Falta el paso 4, o lo cancelaste en GitHub.
Faltan permisos	Cambiaste permisos en la App y la instalación no ha aceptado la actualización: acéptala en GitHub (Settings → Applications → Installed GitHub Apps).
Este enlace para crear la App caducó o ya se usó	El enlace de Crear en GitHub dura una hora y sirve una sola vez: empieza de nuevo desde Integraciones.
GitHub rechaza la Setup URL	Déjala vacía y usa Buscar instalaciones; funciona igual.