Connetti GitHub
Collega il repository GitHub a Jamdesk per distribuzioni automatiche a ogni push. Installazione app, selezione repository e configurazione dei branch.
Jamdesk distribuisce automaticamente la tua documentazione quando esegui il push su GitHub.
Gli screenshot mostrano l'interfaccia in inglese.
Per capire come lavorano insieme la GitHub App e il collegamento dell'account personale, consulta Comprendere l'integrazione GitHub.
Documentazione su Bitbucket Cloud? Consulta Connetti Bitbucket. Ogni progetto si collega a un solo provider. Non hai un account GitHub? Consulta Documentazione senza GitHub.
Installazione dell'app GitHub
Jamdesk ti chiede di installare la GitHub App di Jamdesk la prima volta che accedi. L'app concede:
- Accesso al repository: lettura dei contenuti della documentazione
- Webhook: attivazione delle build al push
- Stato dei commit: visualizzazione dello stato della build sui commit
Autorizzazioni
La GitHub App di Jamdesk richiede questi permessi:
| Permesso | Scopo |
|---|---|
| Contenuti del repository (lettura e scrittura) | Clonare e leggere i file della documentazione. Le scritture avvengono solo quando salvi nell'editor della dashboard, accetti i suggerimenti di Fix with AI o attivi la traduzione |
| Metadati (lettura) | Elencare repository e branch |
| Webhook | Ricevere le notifiche di push |
Jamdesk accede solo ai repository a cui hai concesso esplicitamente l'accesso. Puoi modificare l'accesso in qualsiasi momento nelle impostazioni di GitHub.
Collega un repository
Fai clic su Connect Repository durante la creazione o la modifica di un progetto.
Scegli tra i repository in cui è installata la GitHub App.
Seleziona il branch da distribuire:
- main o master: la scelta più comune per la documentazione di produzione
- docs: se conservi la documentazione in un branch separato
- Qualsiasi branch: per le distribuzioni di anteprima
Se il tuo docs.json non si trova nella radice del repository, indica il percorso:
docs/ # Docs in a subdirectory
packages/docs/ # Monorepo with docs packageLascia vuoto se docs.json si trova nella radice.
La dashboard del progetto mostra quindi il repository e il branch collegati:
Deploy automatici
Ogni push sul branch configurato avvia una build:
git add .
git commit -m "Update API documentation"
git push origin mainLe build di solito si completano in 30-90 secondi. Visualizza lo stato nella dashboard o sul commit di GitHub.
Cambiare repository
Per collegare un repository diverso:
- Vai su Settings → Repository
- Fai clic su Change Repository
- Seleziona il nuovo repository e il branch
Cambiare repository può influire sulla documentazione in produzione. Il nuovo repository deve contenere una configurazione Jamdesk valida.
Gestire l'accesso della GitHub App
Controlla a quali repository Jamdesk può accedere:
- Vai su github.com/settings/installations
- Trova Jamdesk nell'elenco
- Fai clic su Configure
- In "Repository access", seleziona repository specifici o tutti
Repository dell'organizzazione
Un amministratore dell'organizzazione deve approvare l'installazione della GitHub App per i repository dell'organizzazione:
- Richiedi l'installazione dalla dashboard di Jamdesk
- Un amministratore riceve una notifica su GitHub
- Dopo l'approvazione, i repository dell'organizzazione compaiono nel selettore dei repository
Collega il tuo account personale
Collega il tuo account GitHub personale in User Settings per un'attribuzione affidabile delle build:
- Fai clic sul tuo avatar → User Settings
- Trova la sezione GitHub Account
- Fai clic su Link GitHub Account
Questo collegamento è separato dalla GitHub App. Serve ad attribuire i tuoi commit a te. Scopri di più.
Risoluzione dei problemi
Il repository non viene visualizzato
- Verifica che la GitHub App sia installata sul repository
- Per i repository di organizzazioni, conferma che un amministratore abbia approvato l'accesso
- Aggiorna l'elenco dei repository nella dashboard
GitHub continua a reindirizzarti alla pagina dell'app Jamdesk
Probabilmente il tuo account GitHub è gestito dalla tua azienda. GitHub non consente a questi account di installare app autonomamente. Consulta account GitHub gestiti dall'azienda per risolvere.
Usare un account GitHub già usato da un altro account Jamdesk
L'elenco dei repository mostra un messaggio che inizia con:
Another Jamdesk account already uses this GitHub account.
Significa che un progetto di un altro account Jamdesk usa già la GitHub App di Jamdesk su quell'account GitHub. Di solito un collega ha configurato Jamdesk per primo, oppure hai effettuato l'accesso con un secondo account Jamdesk.
Per usare i repository dell'account:
- Fai clic su Verify on GitHub.
- Accedi a GitHub come utente che può eseguire il push sul repository.
- Scegli il repository dall'elenco.
Verify on GitHub collega l'utente GitHub con cui accedi al tuo account Jamdesk, come fa User Settings. Se il browser è già connesso a GitHub con un altro utente, esci prima da GitHub.
L'elenco mostra solo i repository su cui il tuo utente GitHub può eseguire il push. La verifica dura un'ora, quindi scegli il repository poco dopo la verifica. Se Jamdesk indica che GitHub non ha mostrato installazioni utilizzabili, controlla di aver effettuato l'accesso con l'utente GitHub corretto, oppure chiedi a un proprietario dell'account GitHub di concederti l'accesso al repository.
Per lavorare nello stesso progetto, chiedi al suo proprietario di invitarti.
Le build non vengono attivate
- Verifica che il webhook sia attivo nelle impostazioni del repository
- Controlla di eseguire il push sul branch configurato
- Cerca errori di consegna dei webhook in GitHub
Errori di autorizzazione negata
- Riautorizza la GitHub App nelle impostazioni di GitHub
- Conferma che l'app Jamdesk possa accedere al repository
Per una risoluzione dei problemi più dettagliata, consulta Comprendere l'integrazione GitHub.