Conectar Bitbucket
Conecte um repositório Bitbucket Cloud ao Jamdesk, crie um repositório de docs ou vincule um existente e publique a cada push.
O Jamdesk faz o build a partir do Bitbucket Cloud da mesma forma que a partir do GitHub: você autoriza o Jamdesk uma vez e cada push para a branch escolhida publica uma nova versão do seu site. Esta página é destinada a equipes cuja documentação está no Bitbucket ou que querem manter a documentação junto do código que já está lá.
Mantém sua documentação no GitHub? Consulte Conectar GitHub. Um projeto pode se conectar a um único provedor git por vez.
Antes de começar
- Uma conta do Bitbucket Cloud. Bitbucket Data Center e Bitbucket Server não são compatíveis.
- Permissão de administrador no repositório. O Jamdesk instala um webhook de push no repositório, e o Bitbucket permite que apenas administradores de repositórios criem webhooks.
- Um projeto sem repositório conectado. Para mover um projeto do GitHub para o Bitbucket, primeiro desconecte o GitHub em Settings → Git Repository.
- Pop-ups permitidos para o dashboard. O login do Bitbucket é aberto em uma janela pop-up.
O que o Jamdesk solicita
O Jamdesk se conecta por meio de um consumidor OAuth do Bitbucket. Quando você entra, o Bitbucket lista as permissões solicitadas:
| Permissão | Por que o Jamdesk precisa dela |
|---|---|
| Account: Read | Registra qual conta do Bitbucket conectou o projeto, para que os pushes dessa conta sejam reconhecidos |
| Repositories: Read | Clona seu repositório para fazer o build e lista seus repositórios quando você altera o repositório |
| Repositories: Write | Cria o repositório inicial de documentação e envia o conteúdo inicial para ele |
| Webhooks: Read and write | Instala o webhook de push que aciona os builds e o remove quando a conexão é alterada |
O Jamdesk armazena o token de atualização resultante criptografado com o Google Cloud KMS e renova o acesso automaticamente. Você não precisa de uma senha de aplicativo nem de um token de acesso pessoal.
Escolher o Bitbucket para um projeto
Abra o projeto no dashboard. Enquanto nenhum repositório estiver conectado, a página do projeto mostra um card Connect your docs repository com duas opções. Clique em Bitbucket.
A partir daí, você pode deixar que o Jamdesk crie um repositório inicial ou conectar um que já possui.
Criar um repositório inicial de docs
Digite o slug do workspace, a parte da URL do Bitbucket depois de bitbucket.org/. Para https://bitbucket.org/acme/, digite acme.
Clique em Sign in with Bitbucket. Um pop-up será aberto em bitbucket.org. Revise as permissões e conceda acesso.
O Jamdesk cria um repositório nesse workspace, nomeado de acordo com o seu projeto e com o sufixo -docs. Um projeto chamado Acme Docs recebe acme-docs. Se esse nome já estiver em uso, o Jamdesk usará -documentation.
O repositório começa na branch main com a documentação inicial já disponível. O Jamdesk instala o webhook e executa o primeiro build.
Quando o card mostrar Starter docs created and connected!, seu site estará a caminho. Clone o novo repositório e comece a editar.
Conectar um repositório existente
Digite o repositório como workspace/repository-slug, por exemplo acme/developer-docs. As duas partes vêm da URL do repositório em bitbucket.org.
Informe a branch para deploy. Deixe em branco para usar main.
Clique em Connect Bitbucket e conceda acesso no pop-up. Em seguida, o Jamdesk:
- Confirma que sua conta tem permissão de administrador no repositório
- Procura
docs.jsonna raiz do repositório ou em uma subpasta, até três níveis de profundidade - Instala o webhook de push
- Registra seu endereço
yourproject.jamdesk.appe inicia o primeiro build
O repositório precisa ter um docs.json válido na branch informada. Se o Jamdesk não encontrar nenhum, adicione um e conecte novamente. Se encontrar mais de um, mantenha apenas um docs.json por repositório. Um repositório com um mint.json é um projeto Mintlify: execute jamdesk migrate, faça push e conecte novamente.
Depois de conectado, o card do projeto mostra o repositório, a branch e um badge Connected.
Builds automáticos ao fazer push
Cada push para a branch conectada aciona um build:
git add .
git commit -m "Update API documentation"
git push origin mainO Bitbucket entrega um evento de push ao webhook do Jamdesk, e o Jamdesk faz o build desse commit uma vez. Uma entrega duplicada do mesmo commit não inicia um segundo build, e excluir uma branch nunca aciona um build.
O Bitbucket não tenta novamente uma entrega de webhook que falha. Para compensar isso, o Jamdesk também verifica a ponta da sua branch a cada cinco minutos e faz o build de qualquer commit que ainda não tenha sido processado. Um push cujo webhook foi perdido ainda é publicado em poucos minutos.
Os builds manuais pelo dashboard funcionam da mesma forma que nos projetos do GitHub. Consulte Acionar builds.
Quais pushes acionam um build
O Jamdesk faz o build de pushes feitos pela conta do Bitbucket que conectou o projeto ou que o autorizou novamente por último. Um push de qualquer outra conta aparece na lista de builds como um build com falha e erro de autorização, e nada é publicado.
Os projetos do Bitbucket ainda não oferecem suporte à vinculação de uma conta pessoal em User Settings nem à autorização de contas adicionais em Settings → Automation accounts. Se várias pessoas fizerem push para a branch de deploy, conecte o projeto com a conta que faz merge nessa branch ou faça com que essa conta execute o push.
Alterar o repositório ou a branch
Clique em Change repository no card do projeto. O Jamdesk lista os repositórios aos quais sua conta do Bitbucket pode acessar. Escolha um repositório e uma branch e confirme.
O Jamdesk instala o webhook no novo repositório, remove-o do antigo e inicia um build.
Alterar os repositórios afeta sua documentação publicada assim que o build termina. O novo repositório precisa conter um docs.json válido.
Reautorizar uma conexão expirada
O Bitbucket revoga o acesso do Jamdesk quando o usuário conectado o remove no Bitbucket ou quando o token de atualização fica sem uso por vários meses. O card do projeto passa a mostrar um badge Needs reauth e a mensagem Bitbucket connection needs attention.
Clique em Re-authorize e entre novamente. Os builds são retomados, e a próxima verificação de cinco minutos identifica o commit mais recente da sua branch.
Como o Bitbucket difere do GitHub
Os projetos do Bitbucket usam uma única autorização OAuth, enquanto os projetos do GitHub usam um GitHub App e um vínculo opcional com uma conta pessoal. A maior parte da plataforma funciona da mesma maneira. As diferenças são:
| Recurso | GitHub | Bitbucket Cloud |
|---|---|---|
| Build ao fazer push | Webhook | Webhook, além de uma verificação de cinco minutos para entregas perdidas |
| Repositório inicial de docs | Sim | Sim |
| Domínios personalizados, hospedagem em subcaminho, builds manuais, deploys pela CLI | Sim | Sim |
| Status do build nos commits | Exibido no commit no GitHub | Apenas no dashboard |
| Vínculo de conta pessoal para atribuição do build | User Settings | Indisponível. Os builds são atribuídos à conta conectada |
| Lista de permissões de contas de automação | Settings → Automation accounts | Ainda não |
| Editor web | Sim | Ainda não |
| Corrigir com IA | Sim | Ainda não |
| Tradução com IA | Sim | Ainda não |
Excluir um projeto remove o webhook do seu repositório e revoga o acesso do Jamdesk.
Solução de problemas
"Sua conta do Bitbucket não tem permissão de administrador neste repositório"
O Jamdesk precisa de acesso de administrador para instalar o webhook. Peça a um administrador do workspace que conceda a você permissão de administrador no repositório ou faça com que um administrador conecte o projeto.
"Não foi possível encontrar docs.json neste repositório"
O Jamdesk procurou na raiz e em até três pastas de profundidade na branch informada. Adicione um docs.json, faça push para essa branch e conecte novamente. Consulte a referência de docs.json.
"Foram encontrados vários arquivos docs.json"
Mantenha um docs.json por repositório. Remova ou renomeie os outros e conecte novamente.
"Este repositório parece ser um projeto Mintlify"
O repositório contém um mint.json. Execute jamdesk migrate para convertê-lo, faça push do resultado e conecte novamente.
Pop-up bloqueado
Permita pop-ups para o dashboard no navegador e clique novamente em Sign in with Bitbucket ou Connect Bitbucket.
Builds não são acionados
- No Bitbucket, abra Repository settings → Webhooks e confirme que o webhook do Jamdesk está presente e ativo
- Verifique se você está fazendo push para a branch configurada
- Aguarde cinco minutos. A verificação periódica faz o build de qualquer commit que o webhook não identificou
- Se o card do projeto mostrar Needs reauth, reautorize a conexão
- Se o push tiver vindo de outra conta do Bitbucket, consulte Quais pushes acionam um build