Collega Bitbucket

Jamdesk esegue il build da Bitbucket Cloud nello stesso modo in cui lo esegue da GitHub: autorizzi Jamdesk una volta e ogni push sul branch scelto pubblica una nuova versione del sito. Questa pagina è destinata ai team la cui documentazione si trova in Bitbucket o che vogliono mantenere i docs accanto al codice già presente.

Prima di iniziare

• Un account Bitbucket Cloud. Bitbucket Data Center e Bitbucket Server non sono supportati.
• Autorizzazioni di amministratore sul repository. Jamdesk installa un webhook push sul repository e Bitbucket consente solo agli amministratori del repository di creare webhook.
• Un progetto senza repository collegato. Per spostare un progetto da GitHub a Bitbucket, scollega prima GitHub in Settings → Git Repository.
• Popup consentiti per il dashboard. L'accesso a Bitbucket si apre in una finestra popup.

Cosa richiede Jamdesk

Jamdesk si collega tramite un consumer OAuth di Bitbucket. Quando accedi, Bitbucket elenca le autorizzazioni richieste:

Jamdesk archivia il refresh token risultante in forma crittografata con Google Cloud KMS e rinnova autonomamente l'accesso. Non ti servono una password app o un personal access token.

Scegli Bitbucket per un progetto

Apri il progetto nel dashboard. Quando non è collegato alcun repository, la pagina del progetto mostra una card Connect your docs repository con due opzioni. Fai clic su Bitbucket.

Da qui puoi lasciare che Jamdesk crei un repository iniziale oppure collegarne uno che già possiedi.

Crea un repository docs iniziale

Quando la card mostra Starter docs created and connected!, il sito è in fase di pubblicazione. Clona il nuovo repository e inizia a modificarlo.

Collega un repository esistente

Il repository deve contenere un docs.json valido sul branch inserito. Se Jamdesk non ne trova alcuno, aggiungine uno e prova a collegarlo di nuovo. Se ne trova più di uno, mantieni un solo docs.json per repository. Un repository con un mint.json è un progetto Mintlify: esegui jamdesk migrate, invia le modifiche con un push e collegalo di nuovo.

Una volta collegato, la card del progetto mostra il repository, il branch e il badge Connected.

Build automatici sui push

Ogni push sul branch collegato attiva un build:

git add .
git commit -m "Update API documentation"
git push origin main

Bitbucket invia un evento push al webhook di Jamdesk e Jamdesk esegue una volta il build di quel commit. Una consegna duplicata dello stesso commit non avvia un secondo build e l'eliminazione di un branch non attiva mai un build.

Bitbucket non riprova a consegnare un webhook non riuscito. Per compensare, Jamdesk controlla anche la punta del branch ogni cinque minuti ed esegue il build di ogni commit che non ha ancora elaborato. Un push il cui webhook è andato perso viene comunque pubblicato entro pochi minuti.

I build manuali dal dashboard funzionano come per i progetti GitHub. Consulta Attivazione dei build.

Quali push attivano un build

Jamdesk esegue il build dei push effettuati dall'account Bitbucket che ha collegato il progetto o che lo ha riautorizzato per ultimo. Un push proveniente da qualsiasi altro account appare nell'elenco dei build come build non riuscito con un errore di autorizzazione e non viene pubblicato nulla.

Cambia il repository o il branch

Fai clic su Change repository nella card del progetto. Jamdesk elenca i repository a cui il tuo account Bitbucket può accedere. Scegli un repository e un branch, quindi conferma.

Jamdesk installa il webhook sul nuovo repository, lo rimuove da quello precedente e avvia un build.

Riautorizza una connessione scaduta

Bitbucket revoca l'accesso di Jamdesk quando l'utente che ha effettuato il collegamento lo rimuove in Bitbucket o quando il refresh token non viene utilizzato per diversi mesi. La card del progetto mostra quindi il badge Needs reauth e il messaggio Bitbucket connection needs attention.

Fai clic su Re-authorize ed esegui nuovamente l'accesso. I build riprendono e il controllo successivo, dopo cinque minuti, rileva l'ultimo commit sul branch.

Differenze tra Bitbucket e GitHub

I progetti Bitbucket usano una singola autorizzazione OAuth, mentre i progetti GitHub usano una GitHub App e un collegamento facoltativo a un account personale. La maggior parte della piattaforma funziona allo stesso modo. Le differenze sono:

L'eliminazione di un progetto rimuove il webhook dal repository e revoca l'accesso di Jamdesk.

Risoluzione dei problemi

"Your Bitbucket account lacks admin permission on this repository"

Jamdesk necessita dell'accesso di amministratore per installare il webhook. Chiedi a un amministratore del workspace di concederti le autorizzazioni di amministratore sul repository oppure chiedi a un amministratore di collegare il progetto.

"We could not find docs.json in this repository"

Jamdesk ha cercato nella root e fino a tre cartelle di profondità sul branch inserito. Aggiungi un docs.json, invialo con un push su quel branch e prova a collegarlo di nuovo. Consulta il riferimento docs.json.

"Multiple docs.json files were found"

Mantieni un solo docs.json per repository. Rimuovi o rinomina gli altri, quindi prova a collegare di nuovo il repository.

"This repository looks like a Mintlify project"

Il repository contiene un mint.json. Esegui jamdesk migrate per convertirlo, invia il risultato con un push e prova a collegarlo di nuovo.

Popup bloccato

Consenti i popup per il dashboard nel browser, quindi fai nuovamente clic su Sign in with Bitbucket o Connect Bitbucket.

I build non vengono attivati

• In Bitbucket, apri Repository settings → Webhooks e conferma che il webhook di Jamdesk sia presente e attivo
• Verifica di effettuare il push sul branch configurato
• Attendi cinque minuti. Il controllo periodico esegue il build di ogni commit che il webhook non ha rilevato
• Se la card del progetto mostra Needs reauth, riautorizza la connessione
• Se il push proviene da un account Bitbucket diverso, consulta Quali push attivano un build

Cosa fare dopo?