Crear la GitHub App

Esta guía muestra cómo dar a tu servidor su propia identidad de GitHub. Tarda unos dos minutos, solo la hace el propietario del servidor y solo hay que hacerla una vez por servidor.

Puede que no la necesites

Una compilación oficial ya incluye un id de cliente de GitHub, así que Iniciar sesión con GitHub funciona sin más y sin registrar nada: un flujo de dispositivo se autentica solo con el id de cliente, así que es seguro distribuirlo. Registra tu propia app cuando quieras que el SERVIDOR actúe por sí mismo (webhooks, sondeo de PR y sincronización de tickets ejecutándose sobre una instalación de la app en lugar de sobre la credencial de una persona), o cuando estés compilando desde el código fuente.

Para conectar tu propia cuenta después, consulta Configurar la integración con GitHub.

Por qué tu servidor necesita su propia app

De un mismo registro salen dos trabajos distintos, y la app es lo que hace honestos a ambos:

Trabajo	Qué lo responde	Por qué importa
Una persona inicia sesión	El id de cliente de la app, mediante el flujo de dispositivo	Obtienes una credencial que es tuya, en el servidor y en todos los dispositivos, sin ningún token que pegar ni rotar
El servidor actúa	El id de la app + la clave privada → token de instalación	Los webhooks, el sondeo de PR y la sincronización de tickets dejan de depender de que el token de una persona siga siendo válido

Fíjate en lo que no aparece en esa tabla: un secreto de cliente. El flujo de dispositivo de GitHub se autentica solo con el id de cliente (tanto la solicitud del código de dispositivo como el sondeo del token), así que no hay ningún secreto que guardar para iniciar sesión.

Sin una app propia, lo primero sigue funcionando gracias al id de cliente que incluye la compilación; lo segundo recurre a la credencial del propietario del servidor, así que el trabajo en segundo plano depende de quien completó la puesta en marcha primero.

No hay ningún botón de «instalar la GitHub App de Control Center»

Una GitHub App distribuida significaría un secreto de cliente compartido y una instalación compartida entre los servidores de todo el mundo, de modo que el acceso a los repositorios de cada espacio de trabajo pasaría por credenciales que nadie de ese espacio de trabajo controla. Por eso cada servidor tiene su propia app: esta guía va de lo poco que cuesta eso.

Requisitos previos

• Eres el propietario del servidor: las operaciones providerApps.* están restringidas a él, y la tarjeta es invisible para todos los demás
• Una cuenta de GitHub, o una organización en la que puedas crear apps
• Nada accesible públicamente: el inicio de sesión es un flujo de dispositivo, así que el servidor no necesita ningún puerto de entrada, túnel, URL de devolución de llamada ni dominio

Registrar la app

1. Ve a github.com/settings/apps/new (para una organización: Settings → Developer settings → GitHub Apps → New GitHub App)
2. GitHub App name: lo que quieras; Control Center (yourname) sirve. Aparece en los commits y en los comentarios que hace el servidor
3. Homepage URL: lo que quieras, por ejemplo https://github.com/your-name
4. Callback URL: déjala vacía. El flujo de dispositivo no tiene ninguna
5. Marca Enable Device Flow. Es el único ajuste sin el cual el inicio de sesión no puede funcionar
6. Desmarca Webhook → Active a menos que vayas a configurar webhooks por separado
7. En Repository permissions, concede al menos:
   • Contents: Read and write
   • Metadata: Read-only (obligatorio)
   • Pull requests: Read and write
   • Issues: Read and write, si usas GitHub Issues para tus tickets, y para la búsqueda de comentarios del bot en conversaciones de PR (consulta Hablar con Control Center desde una PR de GitHub)
   • Checks: Read-only, para el estado de CI en la página de la PR
8. En Where can this GitHub App be installed?, elige lo que mejor encaje: “Only on this account” es lo adecuado para un servidor personal
9. Haz clic en Create GitHub App

Recoger los tres valores

En la página de la app, justo después de crearla:

Valor	Dónde
App ID	La pestaña General, cerca de arriba
Client ID	La pestaña General, en “Client secrets”
Private key	Generate a private key: se descarga un .pem

El archivo de la clave privada se descarga una sola vez y GitHub no vuelve a mostrarlo nunca. Consérvalo hasta que lo hayas pegado; siempre puedes generar otro.

Un secreto de cliente es opcional y solo aporta una cosa: si dejas activada la opción “Expire user authorization tokens”, es lo que renueva el token de una persona de forma silenciosa en lugar de pedirle que vuelva a iniciar sesión cada ocho horas. El inicio de sesión en sí nunca lo usa.

La configuración más sencilla es desactivar esa caducidad, y entonces no hace falta ningún secreto en ningún sitio. Si la dejas activada, genera un secreto y pégalo en Ajustes → Servidor → Inicio de sesión único (la tarjeta Aplicaciones de proveedor): no hay ninguna variable de entorno para él, y ninguna viene integrada en la compilación, así que se queda en tu servidor.

Instalarla en tu cuenta

Una app que está registrada pero no instalada puede autenticar a personas y no leer nada.

1. En la página de la app, abre Install App
2. Instálala en tu cuenta o en tu organización
3. Elige All repositories, o selecciona los que este servidor deba ver

Pegarla en Control Center

1. Ve a Ajustes → Servidor → Inicio de sesión único y desplázate hasta la tarjeta Aplicaciones de proveedor
2. En el bloque GitHub, establece cada campo:
   • Id de la app: el App ID numérico
   • Clave privada: pega todo el .pem, incluidas las líneas BEGIN y END
   • Id de cliente: el de la misma página
   • Secreto de cliente: solo si has generado uno (para renovar el token)
3. Haz clic en Probar

La clave se analiza a medida que se guarda, así que un pegado truncado o con el formato incorrecto se rechaza ahí mismo en lugar de fallar en una solicitud en segundo plano horas después. Probar va más allá y pregunta a GitHub en qué cuentas está instalada la app: “guardado” y “funciona” son afirmaciones distintas, y solo la segunda significa que algo llegará a ejecutarse.

Punto de control: el bloque de GitHub dice «El servidor puede actuar por sí mismo y las personas pueden iniciar sesión.», y la fila GitHub de Ajustes → Espacio de trabajo → Perfil e identidad → Alojamiento de código ahora ofrece Iniciar sesión con GitHub.

Configurarla con variables de entorno en su lugar

Para una instalación headless o automatizada con scripts, el servidor siembra cada campo desde el entorno la primera vez que no tiene un valor guardado:

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="$(cat control-center.private-key.pem)"
GITHUB_CLIENT_ID=Iv1.0123456789abcdef

No hay ninguna opción de línea de comandos para esto: un secreto en una línea de comandos lo puede leer cualquier proceso del host mediante ps. El entorno es el único sitio donde configurarlos, y prevalece sobre lo que incluya la compilación. .env.template es la lista completa.

Para el desarrollo local, el .env de la raíz del repositorio contiene los mismos valores y el escritorio se los pasa al servidor que lanza. Pon la clave en una sola línea allí: un valor de .env es una línea, y \n entre comillas dobles se descodifica como un salto de línea.

GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEow…\n-----END RSA PRIVATE KEY-----"

GITHUB_APP_ID y GITHUB_APP_PRIVATE_KEY son los mismos nombres que ya lee el bróker de tokens del entorno aislado, así que un host que haya configurado tokens de agente de grano fino obtiene el carril de inicio de sesión gratis. El sembrado ocurre una vez por campo: a partir de ahí gana el valor guardado, así que editar en Ajustes no queda deshecho por el siguiente reinicio.

Haz lo mismo con Linear

Linear no tiene flujo de dispositivo, así que su inicio de sesión es un ida y vuelta por el navegador y sí necesita una URL de devolución de llamada: la tarjeta Aplicaciones de proveedor te muestra exactamente la que debes registrar.

1. Crea una aplicación OAuth en linear.app/settings/api/applications/new
2. Establece la Callback URL en la URL que muestra la tarjeta, tal cual
3. Pega el Client ID y el Client secret en el bloque de Linear
4. Opcionalmente, añade una API key del espacio de trabajo: esa es la credencial que usa el servidor para sincronizar tickets cuando no lo ha pedido ninguna persona

Solución de problemas

El diálogo de inicio de sesión dice que el proveedor no devolvió ningún código de dispositivo

Enable Device Flow está desactivado en la app. Actívalo en General y vuelve a intentarlo.

Probar dice que las credenciales funcionan, pero la app no está instalada en ninguna parte

El registro y la instalación son pasos distintos. Abre Install App en la página de la app e instálala.

Probar dice que no se ha podido leer la clave privada

Pega el archivo .pem completo, incluidas las líneas -----BEGIN y -----END. No se puede usar una clave ed25519 ni EC: las GitHub Apps firman con RSA.

Un miembro ha iniciado sesión pero no ve ningún repositorio

La app no está instalada en la cuenta propietaria de esos repositorios, o su instalación selecciona otros distintos. Su propio inicio de sesión solo concede lo que la app tiene permitido ver.

Guías relacionadas

• Configurar la integración con GitHub
• Hablar con Control Center desde una PR de GitHub
• Conectar un host de código
• Gestionar claves API
• Configurar la integración con Slack