Collegare Bitbucket

Jamdesk compila da Bitbucket Cloud allo stesso modo in cui compila da GitHub. Autorizza Jamdesk una volta sola. Ogni push sul branch scelto pubblicherà poi una nuova versione del tuo sito.

Tieni la documentazione su GitHub? Consulta invece Collegare GitHub. Un progetto si collega a un solo provider git alla volta.

Prima di iniziare

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

Cosa richiede Jamdesk

Jamdesk si collega tramite un consumer OAuth di Bitbucket. Bitbucket elenca i permessi richiesti durante l'accesso:

Permesso	Perché Jamdesk ne ha bisogno
Account: Read	Registra quale account Bitbucket ha collegato il progetto. Jamdesk riconosce i push provenienti da quell'account
Repositories: Read	Clona il repository per compilarlo. Elenca i tuoi repository quando cambi repository
Repositories: Write	Crea il repository di documentazione iniziale e vi carica i contenuti di partenza
Webhooks: Read and write	Installa il webhook di push che avvia le build. Lo rimuove quando la connessione cambia

Jamdesk conserva il refresh token cifrato con Google Cloud KMS. Rinnova l'accesso autonomamente. Non servono app password o token di accesso personali.

Scegli Bitbucket per un progetto

Apri il progetto nella dashboard. La pagina del progetto mostra una scheda Connect your docs repository con due opzioni finché non è collegato alcun repository. Fai clic su Bitbucket.

Lascia che Jamdesk crei un repository iniziale, oppure collegane uno che hai già.

Crea un repository docs iniziale

Inserisci il workspace

Digita lo slug del workspace, cioè la parte dell'URL Bitbucket dopo bitbucket.org/. Per https://bitbucket.org/acme/, inserisci acme.

Accedi con Bitbucket

Fai clic su Sign in with Bitbucket. Si apre un popup su bitbucket.org. Controlla i permessi e concedi l'accesso.

Attendi il repository

Jamdesk crea un repository in quel workspace, con il nome del progetto e il suffisso -docs. Un progetto chiamato Acme Docs ottiene acme-docs. Se il nome è già occupato, Jamdesk usa -documentation.

Il repository parte dal branch main con la documentazione iniziale già presente. Jamdesk installa il webhook ed esegue la prima build.

Quando la scheda mostra Starter docs created and connected!, il tuo sito è in arrivo. Clona il nuovo repository e inizia a modificarlo.

Collega un repository esistente

Inserisci il repository

Digita il repository nel formato workspace/repository-slug, ad esempio acme/developer-docs. Prendi workspace e slug dall'URL del repository su bitbucket.org.

Scegli il branch

Inserisci il branch da pubblicare. Lascia vuoto per usare main.

Collega Bitbucket

Fai clic su Connect Bitbucket e concedi l'accesso nel popup. Jamdesk poi:

Verifica che il tuo account abbia permessi di amministratore sul repository
Cerca docs.json nella radice del repository o in una sottocartella, fino a tre livelli di profondità
Installa il webhook di push
Registra l'indirizzo yourproject.jamdesk.app e avvia la prima build

Il repository richiede un docs.json valido sul branch indicato. Se Jamdesk non ne trova nessuno, aggiungilo e ricollega. 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 su di esso, fai push e ricollega.

La scheda del progetto collegato mostra il repository, il branch e un badge Connected.

Build automatici sui push

Ogni push sul branch collegato avvia una build:

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

Bitbucket invia un evento di push al webhook di Jamdesk. Jamdesk compila quel commit una sola volta. Una consegna duplicata dello stesso commit non avvia una seconda build. L'eliminazione di un branch non avvia mai una build.

Bitbucket non ritenta una consegna del webhook fallita. Jamdesk inoltre controlla la punta del tuo branch ogni cinque minuti e compila ogni commit non ancora compilato. Un push il cui webhook è andato perso viene comunque pubblicato entro pochi minuti.

Le build manuali dalla dashboard funzionano come per i progetti GitHub. Consulta Avviare le build.

Quali push attivano un build

Jamdesk compila i push effettuati dall'account Bitbucket che ha collegato il progetto, o che lo ha riautorizzato per ultimo. Un push da qualsiasi altro account compare nell'elenco delle build come build fallita con un errore di autorizzazione. Nulla viene pubblicato.

I progetti Bitbucket non permettono ancora di collegare un account personale in User Settings né di autorizzare account aggiuntivi in Settings → Automation accounts. Se più persone fanno push sul branch di deploy, collega il progetto con l'account che esegue il merge su quel branch, oppure fai in modo che sia quell'account a fare il push.

Cambia il repository o il branch

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

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

Cambiare repository incide sulla documentazione live non appena la build termina. Il nuovo repository deve contenere un docs.json valido.

Riautorizza una connessione scaduta

Bitbucket revoca l'accesso di Jamdesk quando l'utente che lo ha collegato lo rimuove in Bitbucket, oppure quando il refresh token non viene usato per diversi mesi. La scheda del progetto mostra allora un badge Needs reauth e il messaggio Bitbucket connection needs attention.

Fai clic su Re-authorize e accedi di nuovo. Le build riprendono. Il successivo controllo ogni cinque minuti recupera l'ultimo commit del tuo branch.

Differenze tra Bitbucket e GitHub

I progetti Bitbucket usano un'unica autorizzazione OAuth. I progetti GitHub usano una GitHub App più un collegamento facoltativo dell'account personale. Gran parte della piattaforma funziona allo stesso modo. Le differenze:

Funzionalità	GitHub	Bitbucket Cloud
Build al push	Webhook	Webhook, più un controllo ogni cinque minuti per le consegne perse
Repository di documentazione iniziale	Sì	Sì
Domini personalizzati, hosting in sottopercorso, build manuali, deploy da CLI	Sì	Sì
Stato della build sui commit	Mostrato sul commit in GitHub	Solo dashboard
Collegamento account personale per l'attribuzione delle build	User Settings	Non disponibile. Le build sono attribuite all'account che ha collegato
Elenco di account di automazione	Settings → Automation accounts	Non ancora
Web Editor	Sì	Non ancora
Fix with AI	Sì	Non ancora
Traduzione AI	Sì	Non ancora

Eliminare un progetto rimuove il webhook dal tuo repository e revoca l'accesso di Jamdesk.

Risoluzione dei problemi

"Your Bitbucket account lacks admin permission on this repository"

Jamdesk richiede l'accesso di amministratore per installare il webhook. Chiedi a un amministratore del workspace di concederti il permesso di amministratore sul repository, oppure fatti collegare il progetto da un amministratore.

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

Jamdesk ha cercato nella radice e fino a tre cartelle di profondità nel branch indicato. Aggiungi un docs.json, fai push su quel branch e ricollega. Consulta il riferimento docs.json.

"Multiple docs.json files were found"

Mantieni un solo docs.json per repository. Rimuovi o rinomina gli altri, poi ricollega.

"This repository looks like a Mintlify project"

Il repository contiene un mint.json. Esegui jamdesk migrate per convertirlo, fai push del risultato e ricollega.

Consenti i popup per la dashboard nel browser, poi fai di nuovo clic su Sign in with Bitbucket o Connect Bitbucket.

I build non vengono attivati

In Bitbucket, apri Repository settings → Webhooks e verifica che il webhook di Jamdesk sia presente e attivo
Verifica di fare push sul branch configurato
Attendi cinque minuti. Il controllo periodico compila i commit che il webhook ha perso
Se la scheda del progetto mostra Needs reauth, riautorizza la connessione
Se il push proviene da un account Bitbucket diverso, consulta Quali push avviano una build

Cosa fare dopo?

Crea un progetto

Configura un nuovo progetto Jamdesk

Domini personalizzati

Servi la documentazione dal tuo dominio

Avviare le build

Tutti i modi in cui può partire una build

Struttura delle directory

Organizza la documentazione su larga scala