Conectar GitHub
Conecta tu repositorio de GitHub a Jamdesk para desplegar automáticamente con cada push: instalación, selección de repositorio y configuración de rama.
Jamdesk se integra con GitHub para desplegar automáticamente tu documentación con cada push.
Las capturas de pantalla muestran la interfaz en inglés.
Para obtener más contexto sobre cómo funcionan juntos la aplicación de GitHub y la vinculación de cuenta personal, consulta Comprender la integración con GitHub.
¿Tu documentación está en Bitbucket Cloud? Consulta Conectar Bitbucket. Cada proyecto se conecta a un solo proveedor.
Instalación de la aplicación de GitHub
Cuando inicias sesión en Jamdesk por primera vez, se te pedirá que instales la aplicación de GitHub de Jamdesk. Esta aplicación permite:
- Acceso al repositorio - Leer el contenido de tu documentación
- Webhooks - Activar builds con cada push
- Estado del commit - Mostrar el estado del build en los commits
Permisos
La aplicación de GitHub de Jamdesk solicita estos permisos:
| Permiso | Finalidad |
|---|---|
| Contenido del repositorio (lectura y escritura) | Clonar y leer los archivos de tu documentación. Solo escribe cuando guardas en el editor del dashboard, aceptas sugerencias de Fix with AI o activas la traducción |
| Metadatos (lectura) | Listar repositorios y ramas |
| Webhooks | Recibir notificaciones de push |
Jamdesk solo accede a los repositorios a los que le concedes acceso explícitamente. Puedes modificar el acceso en cualquier momento desde la configuración de GitHub.
Conectar un repositorio
Al crear o editar un proyecto, haz clic en Connect Repository.
Elige entre los repositorios donde la aplicación de GitHub esté instalada.
Selecciona la rama que quieres desplegar:
- main o master - La más común para documentación en producción
- docs - Si mantienes la documentación en una rama separada
- Cualquier rama - Para despliegues de preview
Si tu docs.json no está en la raíz del repositorio, especifica la ruta:
docs/ # Docs in a subdirectory
packages/docs/ # Monorepo with docs packageDéjalo en blanco si docs.json está en la raíz.
Una vez conectado, el dashboard de tu proyecto muestra el repositorio y la rama vinculados:
Despliegues automáticos
Una vez conectado, cada push a tu rama configurada activa un build:
git add .
git commit -m "Update API documentation"
git push origin mainLos builds normalmente se completan en 30 a 90 segundos. Consulta el estado en el dashboard o en el commit de GitHub.
Cambiar de repositorio
Para conectar un repositorio diferente:
- Ve a Settings → Repository
- Haz clic en Change Repository
- Selecciona el nuevo repositorio y la rama
Cambiar de repositorio puede afectar tu documentación en producción. El nuevo repositorio debe contener una configuración de Jamdesk válida.
Administrar el acceso de la aplicación de GitHub
Controla a qué repositorios puede acceder Jamdesk:
- Ve a github.com/settings/installations
- Busca Jamdesk en la lista
- Haz clic en Configure
- En «Repository access», selecciona repositorios específicos o todos
Repositorios de organización
En el caso de los repositorios de organización, un administrador de la organización debe aprobar la instalación de la aplicación de GitHub:
- Solicita la instalación desde tu dashboard de Jamdesk
- Un administrador recibe una notificación en GitHub
- Una vez aprobada, los repositorios de la organización aparecen en el selector de repositorios
Vincular tu cuenta personal
Para una atribución de builds fiable, vincula tu cuenta personal de GitHub en User Settings:
- Haz clic en tu avatar → User Settings
- Busca la sección GitHub Account
- Haz clic en Link GitHub Account
Esto es independiente de la aplicación de GitHub y garantiza que tus commits se te atribuyan correctamente. Más información.
Solución de problemas
El repositorio no aparece
- Verifica que la aplicación de GitHub esté instalada en el repositorio
- En repositorios de organización, confirma que un administrador haya aprobado el acceso
- Intenta actualizar la lista de repositorios en el dashboard
GitHub te sigue redirigiendo a la página de la aplicación de Jamdesk
Es probable que tu empresa gestione tu cuenta de GitHub, y GitHub no permite que estas cuentas instalen aplicaciones en su propia cuenta. Consulta cuentas de GitHub gestionadas por la empresa para solucionarlo.
Los builds no se activan
- Comprueba que el webhook esté activo en la configuración del repositorio
- Verifica que estás haciendo push a la rama configurada
- Busca errores de entrega del webhook en GitHub
Errores de permiso denegado
- Vuelve a autorizar la aplicación de GitHub en la configuración de GitHub
- Asegúrate de que el repositorio sea accesible para la aplicación de Jamdesk
Para una solución de problemas más detallada, consulta Comprender la integración con GitHub.