Jamdesk Documentation logo

Connetti GitHub

Collega il tuo repository GitHub a Jamdesk per deploy automatici a ogni push. Include installazione dell'app, scelta del repository e configurazione del branch.

Jamdesk si integra con GitHub per eseguire automaticamente il deploy della documentazione quando invii modifiche.

Gli screenshot mostrano l'interfaccia in inglese.

Per informazioni sul funzionamento congiunto di GitHub App e collegamento dell'account personale, consulta Informazioni sull'integrazione GitHub.

La documentazione si trova invece in Bitbucket Cloud? Consulta Connetti Bitbucket. Ogni progetto si collega a un solo provider.

Installazione dell'app GitHub

Quando accedi a Jamdesk per la prima volta, ti verrà richiesto di installare la Jamdesk GitHub App. Questa app consente di:

  • Accesso al repository - Leggere i contenuti della documentazione
  • Webhook - Attivare le build al push
  • Stato del commit - Mostrare lo stato della build sui commit

Autorizzazioni

La Jamdesk GitHub App richiede queste autorizzazioni:

AutorizzazioneScopo
Contenuti del repository (lettura)Clonare e leggere i file della documentazione
Metadati (lettura)Elencare repository e branch
WebhookRicevere notifiche dei push

Jamdesk accede solo ai repository a cui concedi esplicitamente l'accesso. Puoi modificare l'accesso in qualsiasi momento nelle impostazioni di GitHub.

Collega un repository

1
Seleziona il repository

Quando crei o modifichi un progetto, fai clic su Connect Repository.

Scegli tra i repository in cui è installata la GitHub App.

2
Scegli il branch

Seleziona il branch su cui eseguire il deploy:

  • main o master - I più comuni per la documentazione in produzione
  • docs - Se mantieni la documentazione in un branch separato
  • Qualsiasi branch - Per i deploy di anteprima
3
Specifica il percorso della documentazione

Se il file docs.json non si trova nella root del repository, specifica il percorso:

docs/           # Docs in a subdirectory
packages/docs/  # Monorepo with docs package

Lascia il campo vuoto se docs.json si trova nella root.

Dopo il collegamento, il dashboard del progetto mostra il repository e il branch collegati:

Dashboard con repository GitHub collegato, badge di stato Linked, nome del repository e branch

Deploy automatici

Dopo il collegamento, ogni push al branch configurato attiva una build:

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

Le build in genere vengono completate in 30-90 secondi. Visualizza lo stato nel dashboard o sul commit GitHub.

Cambiare repository

Per collegare un repository diverso:

  1. Vai a Settings → Repository
  2. Fai clic su Change Repository
  3. Seleziona il nuovo repository e branch

Cambiare repository può influire sulla documentazione pubblicata. Il nuovo repository deve contenere una configurazione Jamdesk valida.

Gestire l'accesso della GitHub App

Controlla a quali repository può accedere Jamdesk:

  1. Vai a github.com/settings/installations
  2. Trova Jamdesk nell'elenco
  3. Fai clic su Configure
  4. In "Repository access", seleziona repository specifici oppure tutti i repository

Repository dell'organizzazione

Per i repository dell'organizzazione, un amministratore dell'organizzazione deve approvare l'installazione della GitHub App:

  1. Richiedi l'installazione dal dashboard di Jamdesk
  2. Un amministratore riceve una notifica in GitHub
  3. Dopo l'approvazione, i repository dell'organizzazione vengono visualizzati nel selettore dei repository

Collega il tuo account personale

Per un'attribuzione affidabile delle build, collega il tuo account GitHub personale in User Settings:

  1. Fai clic sul tuo avatar → User Settings
  2. Individua la sezione GitHub Account
  3. Fai clic su Link GitHub Account

Questa procedura è separata dalla GitHub App e garantisce che i tuoi commit vengano attribuiti correttamente 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 dell'organizzazione, verifica che un amministratore abbia approvato l'accesso
  • Prova ad aggiornare l'elenco dei repository nel dashboard

GitHub continua a reindirizzarti alla pagina dell'app Jamdesk

Probabilmente la tua azienda gestisce il tuo account GitHub e GitHub non consente a questi account di installare app sul proprio account. Consulta account GitHub gestiti dall'azienda per risolvere il problema.

Le build non vengono attivate

  • Verifica che il webhook sia attivo nelle impostazioni del repository
  • Verifica di eseguire il push al branch configurato
  • Cerca gli errori di consegna dei webhook in GitHub

Errori di autorizzazione negata

  • Autorizza nuovamente la GitHub App nelle impostazioni di GitHub
  • Assicurati che il repository sia accessibile alla Jamdesk App

Per una risoluzione dei problemi più dettagliata, consulta Informazioni sull'integrazione GitHub.

Prossimi passi

Crea un progetto

Configura un nuovo progetto Jamdesk

Struttura delle directory

Organizza la documentazione per progetti di qualsiasi dimensione