Integrazione GitHub
Jamdesk utilizza due connessioni GitHub: una GitHub App per accedere ai repository e un collegamento all'account personale per attribuire le build.
Jamdesk utilizza due connessioni GitHub separate, ciascuna con una funzione diversa. Questa pagina spiega cosa fa ogni connessione e quando è necessaria.
In breve: la GitHub App consente a Jamdesk di accedere al repository. Il collegamento all'account personale assicura che i commit siano attribuiti a te.
I progetti Bitbucket Cloud funzionano in modo diverso: una singola autorizzazione OAuth copre l'accesso al repository, il webhook e l'attribuzione delle build. Consulta Connetti Bitbucket.
Panoramica
| Connessione | Scopo | Ambito | Obbligatoria? |
|---|---|---|---|
| GitHub App | Accesso al repository e webhook | Per progetto | Sì |
| Account personale | Identità utente e attribuzione | Per utente | Consigliata |
GitHub App (livello progetto)
La Jamdesk GitHub App viene installata sul tuo account GitHub o sulla tua organizzazione. Concede a Jamdesk l'autorizzazione ad accedere a repository specifici.
Cosa fa
- Legge i contenuti del repository - Clona la documentazione per creare le build
- Riceve i webhook - Riceve una notifica quando esegui il push delle modifiche
- Segnala lo stato della build - Mostra lo stato del deployment sui commit
Perché è necessaria
Senza la GitHub App installata, Jamdesk non può:
- Accedere al repository per creare la documentazione
- Eseguire automaticamente il deployment quando esegui il push delle modifiche
- Mostrare lo stato della build sui commit GitHub
Come funziona
Quando configuri un progetto, Jamdesk ti guida nella connessione a GitHub. Esistono due percorsi.
Crea un repository docs iniziale (impostazione predefinita per i nuovi progetti)
Autorizza Jamdesk per consentirgli di creare un repository sul tuo account o nella tua organizzazione.
Seleziona il tuo account personale o un'organizzazione. Jamdesk crea un nuovo repository precompilato con la documentazione iniziale.
Installa la Jamdesk GitHub App (oppure concedile l'accesso al nuovo repository) per consentirle di creare il build e di eseguire il deployment automatico della documentazione.
Ogni push al branch configurato attiva automaticamente un deployment. Personalizza la documentazione iniziale quando vuoi.
Connetti un repository esistente
Hai già un repository per la documentazione? Installa la Jamdesk GitHub App, concedile l'accesso al repository, quindi scegli il repository e il branch in Jamdesk in Project Settings → Git Repository. Da quel momento, il funzionamento è lo stesso.
Una app, più progetti
Una singola installazione della GitHub App può alimentare più progetti Jamdesk:
- Installa l'app una volta sul tuo account o nella tua organizzazione
- Collega repository diversi a progetti Jamdesk diversi
- Ogni progetto ha la propria configurazione di branch e percorso
Per le organizzazioni, un amministratore deve installare la GitHub App una sola volta. In seguito, ogni membro del team può creare progetti Jamdesk utilizzando i repository a cui l'app ha accesso.
Account GitHub personale (livello utente)
Il collegamento del tuo account GitHub personale associa la tua identità GitHub al tuo profilo Jamdesk. È separato dalla GitHub App.
Cosa fa
- Ti identifica - Associa il tuo nome utente GitHub al tuo account Jamdesk
- Attribuisce le build - Mostra chi ha attivato ogni deployment
- Visibilità del team - Gli altri membri del team possono vedere chi ha apportato le modifiche
Perché è necessario
Quando esegui il push su GitHub, Jamdesk deve determinare quale utente ha attivato la build. Senza il collegamento al tuo account:
- Jamdesk ricorre alla corrispondenza tramite indirizzo email
- Se l'email del tuo commit Git è diversa da quella del tuo account Jamdesk, l'attribuzione non riesce
- La cronologia delle build potrebbe mostrare "Unknown user" per i tuoi commit
Problema comune: Git è configurato con un'email personale, ma ti sei registrato a Jamdesk con un'email di lavoro. Collega il tuo account GitHub per assicurare una corretta attribuzione.
Controlla la tua email Git
git config user.email
git config --global user.email "you@company.com"Usa la stessa email che compare nel tuo account Jamdesk per evitare l'attribuzione "Unknown user" nella cronologia delle build.
Come collegare il tuo account
Fai clic sul tuo avatar in alto a destra, quindi seleziona User Settings.
Scorri fino alla scheda GitHub Account.
Si apre una finestra popup con GitHub. Autorizza Jamdesk a leggere il tuo profilo.
Il tuo nome utente GitHub compare nel tuo profilo Jamdesk.
Come funzionano insieme
Considerale come due chiavi separate:
| Chiave | Apre | Di proprietà di |
|---|---|---|
| GitHub App | Accesso ai repository | Progetto/organizzazione |
| Collegamento personale | La tua identità | Singolo utente |
Esempio di team
Considera un team con 3 sviluppatori che lavorano sulla documentazione aziendale:
- L'amministratore installa la GitHub App nell'organizzazione
- L'amministratore crea il progetto Jamdesk collegato al repository della documentazione
- Ogni sviluppatore collega il proprio account personale
Ora, quando uno sviluppatore esegue un push:
- La GitHub App consente a Jamdesk di leggere il repository e creare la build
- Il collegamento personale identifica chi ha attivato la build
Esempio di sviluppatore singolo
Anche se sei uno sviluppatore singolo, le due connessioni hanno scopi diversi:
- GitHub App - Collega il tuo repository a Jamdesk
- Collegamento personale - Assicura che i tuoi commit mostrino il tuo nome nella cronologia delle build
Disconnessione e scollegamento
Ogni azione rimuove un elemento diverso dell'accesso. Ecco cosa modifica ciascuna di esse.
Disconnettere GitHub (Project Settings)
Cosa fa: rimuove la connessione al repository da un singolo progetto Jamdesk.
Effetti:
- I deployment automatici si interrompono per quel progetto
- La GitHub App resta installata su GitHub
- Gli altri progetti Jamdesk non vengono modificati
- Il collegamento al tuo account personale non viene modificato
Quando usarla: vuoi collegare un repository diverso o interrompere temporaneamente i deployment.
Come riconnettersi: vai a Project Settings → Git Repository e seleziona un repository.
Scollegare GitHub (User Settings)
Cosa fa: rimuove la tua identità GitHub dal tuo profilo Jamdesk.
Effetti:
- Il tuo nome utente GitHub non compare più nel profilo
- L'attribuzione delle build ricorre alla corrispondenza tramite email
- Tutte le connessioni ai repository restano intatte
- La GitHub App resta installata
Quando usarla: vuoi collegare un altro account GitHub o rimuovere la connessione.
Come ricollegarsi: vai a User Settings → GitHub Account → Link GitHub Account.
Disinstallare la GitHub App (su GitHub)
Cosa fa: rimuove completamente l'accesso di Jamdesk al tuo account GitHub.
Effetti:
- Tutti i progetti Jamdesk che utilizzano questa installazione perdono l'accesso
- I deployment automatici si interrompono per tutti i progetti interessati
- I webhook vengono rimossi
- I collegamenti agli account personali non vengono modificati
Disinstalla la GitHub App solo se vuoi rimuovere l'accesso di Jamdesk da TUTTI i tuoi repository. Questa operazione interessa ogni progetto Jamdesk collegato al tuo account GitHub.
Come disinstallarla:
- Vai a GitHub Settings → Applications → Installed GitHub Apps
- Trova "Jamdesk" e fai clic su Configure
- Scorri verso il basso e fai clic su Uninstall
Riferimento rapido
| Azione | Posizione | Ambito | Reversibile? |
|---|---|---|---|
| Disconnettere GitHub | Project Settings → Git Repository | Singolo progetto | Sì - riconnettibile in qualsiasi momento |
| Scollegare GitHub | User Settings → GitHub Account | Il tuo account | Sì - ricollegabile in qualsiasi momento |
| Disinstallare la GitHub App | GitHub Settings | Tutti i progetti | Sì - reinstallabile |
Risoluzione dei problemi
"Hai già installato Jamdesk?"
Se hai già installato la Jamdesk GitHub App, facendo clic su "Install GitHub App" verrai indirizzato alla pagina delle impostazioni di GitHub invece che alla pagina di installazione. È normale. Ecco come completare la configurazione:
Scorri verso il basso fino alla sezione Repository access nella pagina delle impostazioni di GitHub.
Se il pulsante Save è disabilitato (in grigio), passa da "All repositories" a "Only select repositories", quindi torna indietro.
Fai clic sul pulsante verde Save. Jamdesk rileva la modifica e continua la configurazione.
Popup bloccato
Se il popup di GitHub non si apre, il browser potrebbe averlo bloccato. Cerca l'icona del blocco popup nella barra degli indirizzi, consenti i popup da Jamdesk, quindi fai clic su Try Again.
"Le mie build mostrano 'Unknown user'"
Il tuo account GitHub personale non è collegato. Vai a User Settings → Link GitHub Account.
"Il repository non viene visualizzato"
La GitHub App non ha accesso a quel repository. Vai a GitHub Settings, trova Jamdesk e aggiungi il repository.
"Le build non vengono attivate"
- Verifica che il repository sia collegato in Project Settings → Git Repository
- Verifica di eseguire il push al branch configurato
- Controlla la consegna dei webhook nelle impostazioni del repository GitHub
"Non riesco ad accedere ai repository dell'organizzazione"
Un amministratore dell'organizzazione deve approvare l'installazione della GitHub App. Chiedi all'amministratore di installare o approvare Jamdesk nelle impostazioni dell'organizzazione.
"GitHub continua a rimandarmi alla pagina dell'app Jamdesk"
Probabilmente la tua azienda gestisce il tuo account GitHub e GitHub non consente a questi account di installare autonomamente le app. Consulta gli account GitHub gestiti dall'azienda per risolvere il problema.