Configurar la integración de GitHub

Esta guía cubre las partes específicas de GitHub de la configuración. GitHub es uno de los tres hosts de código compatibles — consulta Conectar un host de código para conectar GitLab o Bitbucket, y para saber cómo los combina un espacio de trabajo.

Requisitos previos

Una cuenta de GitHub con acceso a los repos en los que quieres trabajar
Una GitHub App registrada para tu servidor (consulta Crear la GitHub App) para poder iniciar sesión, o un token de acceso personal con repo y read:org que pegar

Iniciar sesión con GitHub

Un flujo de dispositivo: GitHub te muestra un código corto, tú lo apruebas en github.com y el servidor recibe la credencial — sin URL de devolución de llamada, sin puerto y nada que exponer. Disponible siempre que el servidor tenga un id de cliente, que una compilación oficial ya incluye.

Ve a Ajustes → Espacio de trabajo → Perfil e identidad → Alojamiento de código (o al primer paso de la puesta en marcha)
En la fila GitHub, haz clic en Iniciar sesión con GitHub
Un diálogo muestra un código de ocho caracteres y abre github.com/login/device en tu navegador. El código ya está en tu portapapeles
Pégalo, aprueba la app y vuelve. La fila cambia sola a «Sesión iniciada como tu-nombre-de-usuario»

Puedes cerrar el diálogo mientras terminas en el navegador — el servidor sigue sondeando hasta que el código caduque (unos 15 minutos), así que el inicio de sesión se completa de todos modos.

O pegar un token

La alternativa cuando el servidor no tiene app, cuando la app no está instalada en una cuenta que necesitas o cuando simplemente prefieres usar un PAT.

Ve a Ajustes → Espacio de trabajo → Perfil e identidad → Alojamiento de código
En la fila GitHub, haz clic en Añadir token
Pega un token con repo y read:org (clásico) y guarda. Un token de grano fino necesita en el repositorio Contents y Pull requests (read and write), además de Checks y Actions (read).

El token se comprueba tal como se guarda, así que la fila puede nombrar la cuenta a la que pertenece. Haz clic en Desconectar para eliminarlo.

Punto de control: la fila GitHub dice «Sesión iniciada como tu-nombre-de-usuario». Un sufijo indica la fuente cuando la credencial que responde no es la tuya — «mediante la app de este servidor» o «desde el entorno».

Qué te aporta la integración

Función	Cómo
Lista y detalle de PR	La API REST de GitHub, desde el servidor, con la identidad de la app o con tu propia credencial
Ejecuciones de comprobación	La API Checks de GitHub
Publicación de revisiones	Un paso que depende de la acción del usuario y que publica tu revisión en la PR
Registro de repos	Se acepta un checkout si su remoto `origin` apunta a github.com — o a gitlab.com / bitbucket.org
Acceso de los agentes a GitHub	El broker de credenciales inyecta un token de solo lectura como `GH_TOKEN` / `GITHUB_TOKEN`; los push pasan por Control Center
Avisos de notificación	Un sondeo en el servidor de tu bandeja de notificaciones de GitHub genera «Mencionado en pull request» y «Revisión solicitada»
Perfiles de usuario	Tarjetas de perfil al pasar el cursor y filtrado de PR por autor

Algunas rutas usan la API GraphQL en lugar de REST cuando resulta más barato — la actividad de ramas del selector al redactar una PR y el estado de revisión en vivo que decide si una notificación de revisión solicitada sigue pendiente.

Vigila las caídas de GitHub

La barra de título muestra un indicador de estado cuando un proveedor está degradado, e incluye GitHub, Claude, OpenAI y Kimi. Permanece oculto mientras todo va bien — su presencia informa de un problema, no de su ausencia.

Haz clic en el indicador para abrir un panel flotante con el estado de cada proveedor y un botón de actualización. Los estados se actualizan solos cada dos minutos.

Cómo actúan los agentes en GitHub

Un agente que trabaja en un worktree de GitHub recibe siempre un token de GitHub de solo lectura. Un push pasa por Control Center, que pregunta a la regla Enviar a un remoto y luego lo reenvía con un token de escritura que el agente nunca tiene. Consulta Configurar políticas de sandbox
Los commits que hace un agente se firman como el agente — el nombre visible más (agent), en una dirección sintética derivada del id del agente —, nunca como una persona. Quien lo pidió aparece acreditado con un trailer Co-Authored-By
Con una GitHub App configurada, el broker acuña tokens de instalación de grano fino, con alcance de repositorio y alrededor de una hora de vigencia, en cada lanzamiento, en lugar de entregar un token amplio. La instalación se resuelve a partir del propietario del repo de la ejecución, así que una app instalada en varias cuentas se limita correctamente a la que toque la ejecución. Sin app, los agentes reciben el token del entorno, que no se puede restringir a solo lectura: la regla de push vincula entonces git push, pero no el código que usa el token directamente
El token es siempre el del broker, nunca el propio del miembro que lo pide. El token del servidor se retiene a una ejecución que actúa por un miembro que no es el propietario y no ha conectado GitHub

Solución de problemas

La lista de PR está vacía y dice que GitHub no está conectado

No tienes ninguna credencial de GitHub en este servidor. Inicia sesión o pega un token en Alojamiento de código. Los repos de otros hosts de código no se ven afectados — solo los de GitHub no aportan nada.

La fila ofrece «Añadir token» pero no «Iniciar sesión con GitHub»

El servidor no tiene id de cliente — el estado normal en una compilación desde el código fuente, ya que las credenciales solo se incorporan en las compilaciones oficiales. Consulta Crear la GitHub App: se tarda unos dos minutos y solo tiene que hacerlo el propietario del servidor, una vez.

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

La GitHub App existe, pero su casilla Device flow está desactivada. Actívala en los ajustes de la app (General → Device flow) y vuelve a intentarlo.

La fila dice «mediante la app de este servidor» cuando esperaba mi propia cuenta

No has iniciado sesión; lo que ves es la identidad de la app del servidor respondiendo. Haz clic en Iniciar sesión con GitHub en esa fila.

Un PAT de grano fino no muestra el botón de fusionar ni el estado de las comprobaciones

El token necesita Contents y Pull requests (read and write), además de Checks y Actions (read). Después de cambiarlo, pégalo de nuevo en Alojamiento de código.

Se rechaza al agregar un repo

El registro necesita las tres cosas: que la ruta esté dentro de un árbol de trabajo de git, que tenga un remoto origin y que ese remoto apunte a un host de código compatible (github.com, gitlab.com o bitbucket.org). Consulta Agregar repos a un espacio de trabajo.

Todo deja de funcionar un rato tras un uso intenso

Ese es el cortacircuitos del límite de velocidad. GitHub señala su límite principal con un 403 que lleva x-ratelimit-remaining: 0 y la hora de restablecimiento; al ver uno, el cliente hace que las peticiones posteriores fallen localmente, sin ninguna llamada de red, hasta que transcurra la ventana, así que una tormenta de reintentos no puede agravar el límite. Los fallos transitorios se reintentan hasta tres veces con retroceso exponencial, respetando retry-after.