Integración con GitHub
Jamdesk utiliza dos conexiones de GitHub: una GitHub App para el acceso al repositorio y un enlace de cuenta personal para la atribución de builds.
Jamdesk utiliza dos conexiones de GitHub independientes, cada una con una función diferente. Esta página explica qué hace cada conexión y cuándo la necesitas.
Resumen: La GitHub App le da a Jamdesk acceso a tu repositorio. Vincular tu cuenta personal garantiza que tus commits se te atribuyan a ti.
Los proyectos de Bitbucket Cloud funcionan de forma diferente: una única autorización OAuth cubre el acceso al repositorio, el webhook y la atribución de builds. Consulta Conectar Bitbucket.
Descripción general
| Conexión | Propósito | Alcance | ¿Obligatoria? |
|---|---|---|---|
| GitHub App | Acceso al repositorio y webhooks | Por proyecto | Sí |
| Cuenta personal | Identidad del usuario y atribución | Por usuario | Recomendado |
GitHub App (a nivel de proyecto)
La Jamdesk GitHub App se instala en tu cuenta de GitHub u organización. Le otorga a Jamdesk permiso para acceder a repositorios específicos.
Qué hace
- Lee el contenido del repositorio - Clona tu documentación para compilarla
- Recibe webhooks - Recibe notificaciones cuando envías cambios
- Informa el estado del build - Muestra el estado del despliegue en los commits
Por qué lo necesitas
Sin la GitHub App instalada, Jamdesk no puede:
- Acceder a tu repositorio para compilar la documentación
- Desplegar automáticamente cuando envías cambios
- Mostrar el estado del build en los commits de GitHub
Cómo funciona
Cuando configuras un proyecto, Jamdesk te guía para conectar GitHub. Hay dos caminos.
Crear un repositorio de documentación 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 nuevo repositorio prellenado con documentación inicial.
Instala la Jamdesk GitHub App (o concédele acceso al nuevo repositorio) para que pueda compilar y desplegar automáticamente tu documentación.
Cada push a tu rama configurada activa automáticamente un despliegue. Personaliza la documentación inicial cuando quieras.
Conectar un repositorio existente
¿Ya tienes un repositorio de documentación? Instala la Jamdesk GitHub App, concédele acceso a ese repositorio y luego elige el repositorio y la rama en Jamdesk en Project Settings → Git Repository. A partir de ahí, funciona de la misma manera.
Una aplicación, varios proyectos
Una sola instalación de la GitHub App puede dar soporte a varios proyectos de Jamdesk:
- Instala la aplicación una vez en tu cuenta u organización
- Conecta diferentes repositorios a diferentes proyectos de Jamdesk
- Cada proyecto tiene su propia configuración de rama y ruta
Para las organizaciones, un administrador solo necesita instalar la GitHub App una vez. Luego, cualquier miembro del equipo puede crear proyectos de Jamdesk usando repositorios a los que la aplicación 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 los builds - Muestra quién activó cada despliegue
- Visibilidad del equipo - Otros miembros del equipo pueden ver quién hizo los cambios
Por qué lo necesitas
Cuando envías cambios 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 electrónico de tus commits de Git difiere de tu correo electrónico 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 electrónico personal, pero te registraste en Jamdesk con un correo electrónico laboral. Vincula tu cuenta de GitHub para garantizar una atribución correcta.
Verifica tu correo electrónico de Git
git config user.email
git config --global user.email "you@company.com"Usa el mismo correo electrónico 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 en la esquina superior 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 | Abre | Pertenece a |
|---|---|---|
| GitHub App | Acceso a los repositorios | Proyecto/Organización |
| Enlace personal | Tu identidad | Usuario individual |
Ejemplo de equipo
Considera un equipo con 3 desarrolladores que trabajan 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 documentación
- Cada desarrollador vincula su cuenta personal
Ahora, cuando cualquier desarrollador envía cambios:
- La GitHub App permite que Jamdesk lea el repositorio y compile
- El enlace personal identifica quién activó el build
Ejemplo de desarrollador individual
Incluso como desarrollador individual, ambas conexiones cumplen funciones diferentes:
- GitHub App - Conecta tu repositorio con Jamdesk
- Enlace personal - Garantiza que tus commits muestren tu nombre en el historial de builds
Desconectar y desvincular
Cada acción elimina un acceso diferente. Esto es lo que afecta cada una.
Desconectar GitHub (Project Settings)
Qué hace: Elimina la conexión del repositorio de un solo proyecto de Jamdesk.
Efectos:
- Los despliegues automáticos se detienen para ese proyecto
- La GitHub App permanece instalada en GitHub
- Los demás proyectos de Jamdesk no se ven afectados
- Tu enlace de cuenta personal no se ve afectado
Cuándo usarlo: Quieres conectar un repositorio diferente o detener los despliegues temporalmente.
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 repositorios 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 completamente el acceso de Jamdesk a tu cuenta de GitHub.
Efectos:
- Todos los proyectos de Jamdesk que usan esta instalación pierden el acceso
- Los despliegues automáticos se detienen para todos los proyectos afectados
- Se eliminan los webhooks
- Los enlaces de cuenta personal no se ven afectados
Solo desinstala la GitHub App si quieres eliminar el acceso de Jamdesk a 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 | Proyecto único | Sí - puedes reconectar en cualquier momento |
| Desvincular GitHub | User Settings → GitHub Account | Tu cuenta | Sí - puedes volver a vincular en cualquier momento |
| Desinstalar la GitHub App | GitHub Settings | Todos los proyectos | Sí - puedes reinstalarla |
Solución de problemas
"¿Ya tienes Jamdesk instalado?"
Si ya instalaste antes la Jamdesk GitHub App, al hacer clic en "Install GitHub App" se 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 bloqueo de ventanas emergentes en tu 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 enviando cambios a la rama configurada
- Verifica la entrega de webhooks en la configuración del repositorio de GitHub
Si todo eso está bien, es posible que quien hizo el push no sea miembro del proyecto. Jamdesk solo compila los pushes de miembros del proyecto. Identifica a quien hizo el push por su cuenta de GitHub vinculada, o porque el correo de su commit coincide con el correo con el que inicia sesión en Jamdesk.
Si no hay coincidencia, el build aparece como fallido con el motivo, y el propietario del proyecto recibe un correo, como máximo uno por semana por persona. Un push que no cambia nada en tu carpeta de documentación no envía ninguno.
Para solucionarlo, invita a la persona en Project Settings → Members usando el correo de su commit. Debe iniciar sesión en Jamdesk con ese correo para aceptar. Si ya es miembro, puede vincular su cuenta de GitHub en User Settings.
"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. Pide a tu administrador que instale o apruebe Jamdesk en la configuración de la organización.
"GitHub sigue enviándome de vuelta a la página de la aplicación Jamdesk"
Es probable que tu empresa administre tu cuenta de GitHub, y GitHub no permite que estas cuentas instalen aplicaciones en su propia cuenta. Consulta cuentas de GitHub administradas por la empresa para solucionarlo.