Conectar Bitbucket
Conecte um repositório Bitbucket Cloud ao Jamdesk. Crie um repositório inicial de docs ou vincule um existente; cada push para a branch publica sua documentação.
O Jamdesk faz o build a partir do Bitbucket Cloud da mesma forma que a partir do GitHub. Autorize o Jamdesk uma vez. Em seguida, cada push para a branch escolhida publica uma nova versão do seu site.
Mantém sua documentação no GitHub? Consulte Conectar GitHub. Um projeto se conecta a um provedor Git por vez.
Antes de começar
- Uma conta Bitbucket Cloud. Bitbucket Data Center e Bitbucket Server não são suportados.
- Permissão de administrador no repositório. O Jamdesk instala um webhook de push no repositório. O Bitbucket só permite que administradores do repositório criem webhooks.
- Um projeto sem repositório conectado. Para mover um projeto do GitHub para o Bitbucket, desconecte primeiro o GitHub em Settings → Git Repository.
- Pop-ups permitidos para o painel. O login do Bitbucket abre em uma janela pop-up.
O que o Jamdesk solicita
O Jamdesk se conecta por meio de um consumidor OAuth do Bitbucket. O Bitbucket lista as permissões solicitadas no login:
| Permissão | Por que o Jamdesk precisa dela |
|---|---|
| Account: Read | Registra qual conta Bitbucket conectou o projeto. O Jamdesk reconhece pushes dessa conta |
| Repositories: Read | Clona seu repositório para fazer o build. Lista seus repositórios quando você troca de repositório |
| Repositories: Write | Cria o repositório inicial de docs e envia o conteúdo inicial para ele |
| Webhooks: Read and write | Instala o webhook de push que dispara os builds. Remove-o quando a conexão muda |
O Jamdesk armazena o refresh token criptografado com o Google Cloud KMS. Ele renova o acesso automaticamente. Você não precisa de senha de aplicativo nem de token de acesso pessoal.
Escolher o Bitbucket para um projeto
Abra o projeto no painel. A página do projeto mostra um cartão Connect your docs repository com duas opções enquanto nenhum repositório estiver conectado. Clique em Bitbucket.
Deixe o Jamdesk criar um repositório inicial ou conecte um que você já tenha.
Criar um repositório inicial de docs
Digite o slug do workspace, a parte da sua URL do Bitbucket depois de bitbucket.org/. Para https://bitbucket.org/acme/, informe acme.
Clique em Sign in with Bitbucket. Um pop-up abre em bitbucket.org. Revise as permissões e conceda o acesso.
O Jamdesk cria um repositório nesse workspace, com o nome do projeto e o sufixo -docs. Um projeto chamado Acme Docs recebe acme-docs. Se esse nome já estiver em uso, o Jamdesk usa -documentation.
O repositório começa na branch main com a documentação inicial já no lugar. O Jamdesk instala o webhook e executa o primeiro build.
Quando o cartão exibir Starter docs created and connected!, seu site está 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. Pegue o workspace e o slug na URL do repositório em bitbucket.org.
Informe a branch a ser publicada. Deixe em branco para usar main.
Clique em Connect Bitbucket e conceda o 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 de 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 um único docs.json por repositório. Um repositório com mint.json é um projeto Mintlify: execute jamdesk migrate nele, faça o push e conecte novamente.
O cartão do projeto conectado mostra o repositório, a branch e um selo Connected.
Builds automáticos ao fazer push
Cada push para a branch conectada dispara um build:
git add .
git commit -m "Update API documentation"
git push origin mainO Bitbucket envia um evento de push para o webhook do Jamdesk. O Jamdesk faz o build desse commit uma única vez. Uma entrega duplicada do mesmo commit não inicia um segundo build. Excluir uma branch nunca dispara um build.
O Bitbucket não tenta novamente uma entrega de webhook que falhou. Por 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 construído. Um push cujo webhook foi perdido ainda assim é publicado em poucos minutos.
Os builds manuais pelo painel funcionam da mesma forma que nos projetos GitHub. Consulte Disparar builds.
Quais pushes acionam um build
O Jamdesk faz o build de pushes feitos pela conta Bitbucket que conectou o projeto, ou que o autorizou pela última vez. Um push de qualquer outra conta aparece na lista de builds como um build com falha e erro de autorização. Nada é publicado.
Os projetos Bitbucket ainda não permitem vincular uma conta pessoal em User Settings nem autorizar contas adicionais em Settings → Automation accounts. Se várias pessoas fizerem push para a branch de publicação, conecte o projeto com a conta que faz merge nessa branch, ou faça com que essa conta seja a responsável pelos pushes.
Alterar o repositório ou a branch
Clique em Change repository no cartão do projeto. O Jamdesk lista os repositórios aos quais sua conta Bitbucket tem acesso. 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.
Trocar de repositório afeta sua documentação publicada assim que o build terminar. 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 que conectou o projeto o remove no Bitbucket, ou quando o refresh token fica sem uso por vários meses. O cartão do projeto então exibe um selo Needs reauth e a mensagem Bitbucket connection needs attention.
Clique em Re-authorize e faça login novamente. Os builds são retomados. A próxima verificação de cinco minutos pega o commit mais recente da sua branch.
Como o Bitbucket difere do GitHub
Os projetos Bitbucket usam uma única autorização OAuth. Os projetos GitHub usam um GitHub App mais um vínculo opcional de conta pessoal. A maior parte da plataforma funciona da mesma forma. As diferenças:
| Recurso | GitHub | Bitbucket Cloud |
|---|---|---|
| Build a cada push | Webhook | Webhook, mais uma verificação a cada 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 de build nos commits | Exibido no commit do GitHub | Somente no painel |
| Vínculo de conta pessoal para atribuição de builds | User Settings | Não disponível. Os builds são atribuídos à conta que conectou |
| Lista de contas de automação | Settings → Automation accounts | Ainda não |
| Web Editor | Sim | Ainda não |
| Fix with AI | Sim | Ainda não |
| AI Translation | 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 peça a um administrador que 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, envie-o para essa branch e conecte novamente. Consulte a referência do docs.json.
"Foram encontrados vários arquivos docs.json"
Mantenha um único docs.json por repositório. Remova ou renomeie os outros e conecte novamente.
"Este repositório parece ser um projeto Mintlify"
O repositório tem um mint.json. Execute jamdesk migrate para convertê-lo, faça o push do resultado e conecte novamente.
Pop-up bloqueado
Permita pop-ups para o painel no seu 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 tenha perdido
- Se o cartão do projeto mostrar Needs reauth, reautorize a conexão
- Se o push veio de outra conta Bitbucket, consulte Quais pushes disparam um build