Conectar Bitbucket
Conecta un repositorio de Bitbucket Cloud a Jamdesk. Crea un repositorio de documentación inicial o vincula uno existente: cada push despliega tus docs.
Jamdesk crea builds desde Bitbucket Cloud de la misma forma que desde GitHub: autorizas Jamdesk una vez, y cada push a la rama elegida publica una nueva versión de tu sitio. Esta página es para equipos cuya documentación vive en Bitbucket, o que quieren mantener sus docs junto al código que ya está ahí.
¿Mantienes tus docs en GitHub? Consulta Conectar GitHub. Un proyecto se conecta a un solo proveedor de Git a la vez.
Antes de empezar
- Una cuenta de Bitbucket Cloud. Bitbucket Data Center y Bitbucket Server no son compatibles.
- Permiso de administrador en el repositorio. Jamdesk instala un webhook de push en el repositorio, y Bitbucket solo permite a los administradores del repositorio crear webhooks.
- Un proyecto sin repositorio conectado. Para mover un proyecto de GitHub a Bitbucket, desconecta primero GitHub en Settings → Git Repository.
- Ventanas emergentes permitidas para el dashboard. El inicio de sesión de Bitbucket se abre en una ventana emergente.
Qué solicita Jamdesk
Jamdesk se conecta mediante un consumidor OAuth de Bitbucket. Al iniciar sesión, Bitbucket enumera los permisos solicitados:
| Permiso | Por qué Jamdesk lo necesita |
|---|---|
| Account: Read | Registra qué cuenta de Bitbucket conectó el proyecto, para que los push de esa cuenta se reconozcan |
| Repositories: Read | Clona tu repositorio para construirlo, y lista tus repositorios cuando cambias de repositorio |
| Repositories: Write | Crea el repositorio de documentación inicial y le envía el contenido inicial |
| Webhooks: Read and write | Instala el webhook de push que activa los builds, y lo elimina cuando cambia la conexión |
Jamdesk almacena el token de actualización resultante cifrado con Google Cloud KMS y renueva el acceso por sí solo. No necesitas una contraseña de aplicación ni un token de acceso personal.
Elegir Bitbucket para un proyecto
Abre el proyecto en el dashboard. Mientras no haya ningún repositorio conectado, la página del proyecto muestra una tarjeta Connect your docs repository con dos opciones. Haz clic en Bitbucket.
Desde ahí puedes dejar que Jamdesk cree un repositorio inicial o conectar uno que ya tengas.
Crear un repositorio de documentación inicial
Escribe el slug del workspace, la parte de tu URL de Bitbucket después de bitbucket.org/. Para https://bitbucket.org/acme/, escribe acme.
Haz clic en Sign in with Bitbucket. Se abre una ventana emergente en bitbucket.org. Revisa los permisos y concede el acceso.
Jamdesk crea un repositorio en ese workspace, con el nombre de tu proyecto seguido del sufijo -docs. Un proyecto llamado Acme Docs obtiene acme-docs. Si ese nombre ya está en uso, Jamdesk usa -documentation en su lugar.
El repositorio comienza en la rama main con documentación inicial ya lista. Jamdesk instala el webhook y ejecuta el primer build.
Cuando la tarjeta muestre Starter docs created and connected!, tu sitio ya está en camino. Clona el nuevo repositorio y empieza a editar.
Conectar un repositorio existente
Escribe el repositorio como workspace/repository-slug, por ejemplo acme/developer-docs. Ambas partes provienen de la URL del repositorio en bitbucket.org.
Introduce la rama a desplegar. Déjala en blanco para usar main.
Haz clic en Connect Bitbucket y concede el acceso en la ventana emergente. Jamdesk entonces:
- Confirma que tu cuenta tiene permiso de administrador en el repositorio
- Busca
docs.jsonen la raíz del repositorio o en una subcarpeta, hasta tres niveles de profundidad - Instala el webhook de push
- Registra tu dirección
yourproject.jamdesk.appe inicia el primer build
El repositorio necesita un docs.json válido en la rama que introdujiste. Si Jamdesk no encuentra ninguno, añade uno y vuelve a conectar. Si encuentra más de uno, mantén un único docs.json por repositorio. Un repositorio con un mint.json es un proyecto Mintlify: ejecuta jamdesk migrate en él, haz push, y vuelve a conectar.
Una vez conectado, la tarjeta del proyecto muestra el repositorio, la rama y una insignia Connected.
Builds automáticos al hacer push
Cada push a la rama conectada activa un build:
git add .
git commit -m "Update API documentation"
git push origin mainBitbucket entrega un evento de push al webhook de Jamdesk, y Jamdesk construye ese commit una sola vez. Una entrega duplicada del mismo commit no inicia un segundo build, y eliminar una rama nunca activa un build.
Bitbucket no reintenta la entrega de un webhook que falla. Para cubrir eso, Jamdesk también verifica la punta de tu rama cada cinco minutos y construye cualquier commit que aún no haya construido. Un push cuyo webhook se perdió igual se despliega en unos minutos.
Los builds manuales desde el dashboard funcionan igual que para los proyectos de GitHub. Consulta Activar builds.
Qué pushes activan un build
Jamdesk construye los push realizados por la cuenta de Bitbucket que conectó el proyecto, o que lo reautorizó por última vez. Un push de cualquier otra cuenta aparece en la lista de builds como un build fallido con un error de autorización, y no se despliega nada.
Los proyectos de Bitbucket aún no admiten vincular una cuenta personal en User Settings ni autorizar cuentas adicionales en Settings → Automation accounts. Si varias personas hacen push a la rama de despliegue, conecta el proyecto con la cuenta que fusiona a esa rama, o haz que esa cuenta se encargue de los push.
Cambiar el repositorio o la rama
Haz clic en Change repository en la tarjeta del proyecto. Jamdesk lista los repositorios a los que tu cuenta de Bitbucket tiene acceso. Elige un repositorio y una rama, y confirma.
Jamdesk instala el webhook en el nuevo repositorio, lo elimina del anterior, y comienza un build.
Cambiar de repositorio afecta a tu documentación en vivo en cuanto termina el build. El nuevo repositorio debe contener un docs.json válido.
Reautorizar una conexión expirada
Bitbucket revoca el acceso de Jamdesk cuando el usuario que conectó lo retira en Bitbucket, o cuando el token de actualización queda sin usar durante varios meses. La tarjeta del proyecto muestra entonces una insignia Needs reauth y el mensaje Bitbucket connection needs attention.
Haz clic en Re-authorize e inicia sesión de nuevo. Los builds se reanudan, y la siguiente verificación de cinco minutos recoge el último commit de tu rama.
En qué se diferencia Bitbucket de GitHub
Los proyectos de Bitbucket usan una única autorización OAuth, mientras que los proyectos de GitHub usan una GitHub App más un enlace opcional de cuenta personal. La mayor parte de la plataforma funciona igual. Las diferencias:
| Función | GitHub | Bitbucket Cloud |
|---|---|---|
| Build al hacer push | Webhook | Webhook, más una verificación cada cinco minutos para entregas perdidas |
| Repositorio de documentación inicial | Sí | Sí |
| Dominios personalizados, alojamiento en subruta, builds manuales, despliegues por CLI | Sí | Sí |
| Estado del build en los commits | Se muestra en el commit en GitHub | Solo en el dashboard |
| Enlace de cuenta personal para la atribución de builds | User Settings | No disponible. Los builds se atribuyen a la cuenta conectada |
| Lista de cuentas de automatización permitidas | Settings → Automation accounts | Aún no |
| Editor Web | Sí | Aún no |
| Corregir con IA | Sí | Aún no |
| Traducción con IA | Sí | Aún no |
Eliminar un proyecto quita el webhook de tu repositorio y revoca el acceso de Jamdesk.
Solución de problemas
«Tu cuenta de Bitbucket no tiene permiso de administrador en este repositorio»
Jamdesk necesita acceso de administrador para instalar el webhook. Pide a un administrador del workspace que te conceda permiso de administrador en el repositorio, o haz que un administrador conecte el proyecto.
«No pudimos encontrar docs.json en este repositorio»
Jamdesk buscó en la raíz y hasta tres carpetas de profundidad en la rama que introdujiste. Añade un docs.json, súbelo a esa rama, y vuelve a conectar. Consulta la referencia de docs.json.
«Se encontraron varios archivos docs.json»
Mantén un único docs.json por repositorio. Elimina o renombra los demás, y vuelve a conectar.
«Este repositorio parece un proyecto Mintlify»
El repositorio tiene un mint.json. Ejecuta jamdesk migrate para convertirlo, haz push del resultado, y vuelve a conectar.
Ventana emergente bloqueada
Permite las ventanas emergentes para el dashboard en tu navegador, y vuelve a hacer clic en Sign in with Bitbucket o Connect Bitbucket.
Los builds no se activan
- En Bitbucket, abre Repository settings → Webhooks y confirma que el webhook de Jamdesk está presente y activo
- Verifica que estás haciendo push a la rama configurada
- Espera cinco minutos. La verificación periódica construye cualquier commit que el webhook haya pasado por alto
- Si la tarjeta del proyecto muestra Needs reauth, reautoriza la conexión
- Si el push vino de una cuenta de Bitbucket diferente, consulta Qué pushes activan un build