Integración con GitHub
Jamdesk usa dos conexiones de GitHub: una GitHub App para acceder al repositorio y una vinculación de cuenta personal para la atribución de builds.
Jamdesk usa dos conexiones de GitHub independientes, cada una con una función distinta. Esta página explica qué hace cada conexión y cuándo la necesitas.
TL;DR: La GitHub App le da a Jamdesk acceso a tu repositorio. Vincular tu cuenta personal asegura que tus commits se atribuyan a ti.
Descripción general
| Conexión | Propósito | Alcance | ¿Requerida? |
|---|---|---|---|
| GitHub App | Acceso al repositorio y webhooks | Por proyecto | Sí |
| Cuenta personal | Identidad del usuario y atribución | Por usuario | Recomendada |
GitHub App (a nivel de proyecto)
La Jamdesk GitHub App se instala en tu cuenta de GitHub o en tu organización. Le otorga a Jamdesk permiso para acceder a repositorios específicos.
Qué hace
- Lee el contenido del repositorio - Clona tus docs para hacer el build
- Recibe webhooks - Se le notifica cuando haces push de cambios
- Reporta el estado del build - Muestra el estado del deployment en los commits
Por qué la necesitas
Sin la GitHub App instalada, Jamdesk no puede:
- Acceder a tu repositorio para hacer el build de la documentación
- Desplegar automáticamente cuando haces push de cambios
- Mostrar el estado del build en los commits de GitHub
Cómo funciona
Cuando configuras un proyecto, Jamdesk te guía por el proceso de conectar GitHub. Hay dos caminos.
Crear un repositorio de docs inicial (predeterminado para proyectos nuevos)
Autoriza a Jamdesk para que pueda crear un repositorio en tu cuenta u organización.
Elige tu cuenta personal o una organización. Jamdesk crea un repositorio nuevo prellenado con documentación inicial.
Instala la Jamdesk GitHub App (u otórgale acceso al repositorio nuevo) para que pueda hacer el build y desplegar automáticamente tus docs.
Cada push a tu branch configurada activa automáticamente un deployment. Personaliza la documentación inicial cuando quieras.
Conectar un repositorio existente
¿Ya tienes un repositorio de documentación? Instala la Jamdesk GitHub App, otórgale acceso a ese repositorio y luego elige el repositorio y la branch en Jamdesk en Project Settings → Git Repository. A partir de ahí funciona de la misma manera.
Una app, múltiples proyectos
Una sola instalación de la GitHub App puede potenciar múltiples proyectos de Jamdesk:
- Instala la app una vez en tu cuenta u organización
- Conecta diferentes repositorios a diferentes proyectos de Jamdesk
- Cada proyecto tiene su propia configuración de branch y ruta
Para organizaciones, un administrador solo necesita instalar la GitHub App una vez. Luego cualquier miembro del equipo puede crear proyectos de Jamdesk usando los repositorios a los que la app tiene acceso.
Cuenta personal de GitHub (a nivel de usuario)
Vincular tu cuenta personal de GitHub asocia tu identidad de GitHub con tu perfil de Jamdesk. Esto es independiente de la GitHub App.
Qué hace
- Te identifica - Asocia tu nombre de usuario de GitHub con tu cuenta de Jamdesk
- Atribuye builds - Muestra quién activó cada deployment
- Visibilidad para el equipo - Otros miembros del equipo pueden ver quién hizo los cambios
Por qué la necesitas
Cuando haces push a GitHub, Jamdesk necesita determinar qué usuario activó el build. Sin tu cuenta vinculada:
- Jamdesk recurre a la coincidencia por dirección de correo electrónico
- Si el correo de tus commits de Git es distinto al de tu cuenta de Jamdesk, la atribución falla
- El historial de builds puede mostrar "Unknown user" para tus commits
Problema común: Tu Git está configurado con un correo personal, pero te registraste en Jamdesk con un correo de trabajo. Vincula tu cuenta de GitHub para asegurar una atribución correcta.
Verifica tu correo de Git
git config user.email
git config --global user.email "you@company.com"Usa el mismo correo que aparece en tu cuenta de Jamdesk para evitar la atribución "Unknown user" en el historial de builds.
Cómo vincular tu cuenta
Haz clic en tu avatar arriba a la derecha y luego selecciona User Settings.
Desplázate hasta la tarjeta GitHub Account.
Se abre una ventana emergente hacia GitHub. Autoriza a Jamdesk a leer tu perfil.
Tu nombre de usuario de GitHub aparece en tu perfil de Jamdesk.
Cómo funcionan juntas
Piensa en ellas como dos llaves independientes:
| Llave | Da acceso a | Pertenece a |
|---|---|---|
| GitHub App | Acceso a los repositorios | Proyecto/Organización |
| Vinculación personal | Tu identidad | Usuario individual |
Ejemplo de equipo
Considera un equipo con 3 desarrolladores trabajando en la documentación de la empresa:
- El administrador instala la GitHub App en la organización
- El administrador crea un proyecto de Jamdesk conectado al repositorio de docs
- Cada desarrollador vincula su cuenta personal
Ahora, cuando cualquier desarrollador hace push:
- La GitHub App le permite a Jamdesk leer el repositorio y hacer el build
- La vinculación personal identifica quién activó el build
Ejemplo de desarrollador individual
Incluso como desarrollador individual, ambas conexiones cumplen funciones distintas:
- GitHub App - Conecta tu repositorio con Jamdesk
- Vinculación personal - Asegura que tus commits muestren tu nombre en el historial de builds
Desconectar y desvincular
Cada acción elimina una parte distinta del acceso. A continuación se explica qué afecta cada una.
Desconectar GitHub (Project Settings)
Qué hace: Elimina la conexión del repositorio de un solo proyecto de Jamdesk.
Efectos:
- Los deployments automáticos se detienen para ese proyecto
- La GitHub App permanece instalada en GitHub
- Otros proyectos de Jamdesk no se ven afectados
- La vinculación de tu cuenta personal no se ve afectada
Cuándo usarlo: Quieres conectar un repositorio diferente o detener temporalmente los deployments.
Cómo reconectar: Ve a Project Settings → Git Repository y selecciona un repositorio.
Desvincular GitHub (User Settings)
Qué hace: Elimina tu identidad de GitHub de tu perfil de Jamdesk.
Efectos:
- Tu nombre de usuario de GitHub ya no aparece en tu perfil
- La atribución de builds recurre a la coincidencia por correo electrónico
- Todas las conexiones de repositorio permanecen intactas
- La GitHub App permanece instalada
Cuándo usarlo: Quieres vincular una cuenta de GitHub diferente o eliminar la conexión.
Cómo volver a vincular: Ve a User Settings → GitHub Account → Link GitHub Account.
Desinstalar la GitHub App (en GitHub)
Qué hace: Elimina por completo el acceso de Jamdesk a tu cuenta de GitHub.
Efectos:
- Todos los proyectos de Jamdesk que usan esta instalación pierden el acceso
- Los deployments automáticos se detienen para todos los proyectos afectados
- Se eliminan los webhooks
- Las vinculaciones de cuentas personales no se ven afectadas
Desinstala la GitHub App solo si quieres eliminar el acceso de Jamdesk de TODOS tus repositorios. Esto afecta a todos los proyectos de Jamdesk conectados a tu cuenta de GitHub.
Cómo desinstalar:
- Ve a GitHub Settings → Applications → Installed GitHub Apps
- Busca "Jamdesk" y haz clic en Configure
- Desplázate hacia abajo y haz clic en Uninstall
Referencia rápida
| Acción | Ubicación | Alcance | ¿Reversible? |
|---|---|---|---|
| Desconectar GitHub | Project Settings → Git Repository | Un solo proyecto | Sí - reconecta cuando quieras |
| Desvincular GitHub | User Settings → GitHub Account | Tu cuenta | Sí - vuelve a vincular cuando quieras |
| Desinstalar la GitHub App | GitHub Settings | Todos los proyectos | Sí - reinstala |
Solución de problemas
"¿Ya tienes Jamdesk instalado?"
Si ya instalaste antes la Jamdesk GitHub App, al hacer clic en "Install GitHub App" te lleva a la página de configuración de GitHub en lugar de a la página de instalación. ¡Esto es normal! Así es como completas la configuración:
Desplázate hasta la sección Repository access en la página de configuración de GitHub.
Si el botón Save está deshabilitado (en gris), cambia de "All repositories" a "Only select repositories" y luego vuelve a cambiarlo.
Haz clic en el botón verde Save. Jamdesk detecta el cambio y continúa con la configuración.
Ventana emergente bloqueada
Si la ventana emergente de GitHub no se abre, es posible que tu navegador la haya bloqueado. Busca un ícono de bloqueador de ventanas emergentes en la barra de direcciones, permite las ventanas emergentes de Jamdesk y luego haz clic en Try Again.
"Mis builds muestran 'Unknown user'"
Tu cuenta personal de GitHub no está vinculada. Ve a User Settings → Link GitHub Account.
"El repositorio no aparece"
La GitHub App no tiene acceso a ese repositorio. Ve a GitHub Settings, busca Jamdesk y agrega el repositorio.
"Los builds no se activan"
- Verifica que el repositorio esté conectado en Project Settings → Git Repository
- Verifica que estés haciendo push a la branch configurada
- Verifica la entrega de webhooks en la configuración del repositorio en GitHub
"No puedo acceder a los repositorios de la organización"
Un administrador de la organización debe aprobar la instalación de la GitHub App. Pídele a tu administrador que instale o apruebe Jamdesk en la configuración de la organización.