Integrazione GitHub
Jamdesk usa due connessioni GitHub: un'app GitHub per l'accesso al repository e un collegamento dell'account personale per l'attribuzione delle build.
Jamdesk utilizza due connessioni GitHub separate con compiti diversi.
In breve: L'app GitHub dà a Jamdesk accesso al tuo repository. Collegare il tuo account personale attribuisce i tuoi commit a te.
I progetti Bitbucket Cloud funzionano diversamente. Una singola autorizzazione OAuth copre l'accesso al repository, il webhook e l'attribuzione delle build. Vedi Collegare Bitbucket.
Panoramica
| Connessione | Scopo | Ambito | Obbligatoria? |
|---|---|---|---|
| App GitHub | Accesso al repository e webhook | Per progetto | Sì |
| Account personale | Identità utente e attribuzione | Per utente | Consigliata |
GitHub App (livello progetto)
La app GitHub di Jamdesk è installata sul tuo account GitHub o sulla tua organizzazione. Dà a Jamdesk accesso ai repository che scegli.
Cosa fa
- Legge il contenuto del repository: clona la tua documentazione per costruirla
- Riceve i webhook: viene avvisata quando esegui il push delle modifiche
- Segnala lo stato della build: mostra lo stato di deployment sui commit
Perché è necessaria
Senza l'app GitHub installata, Jamdesk non può:
- Accedere al tuo repository per costruire la documentazione
- Effettuare il deployment automatico quando esegui il push delle modifiche
- Mostrare lo stato della build sui commit GitHub
Come funziona
La configurazione del progetto ti guida nel collegamento a GitHub. Scegli uno dei due percorsi.
Crea un repository docs iniziale (impostazione predefinita per i nuovi progetti)
Autorizza Jamdesk a creare un repository sul tuo account o sulla tua organizzazione.
Scegli il tuo account personale o un'organizzazione. Jamdesk crea un nuovo repository precompilato con una documentazione di partenza.
Installa l'app GitHub di Jamdesk (o concedile l'accesso al nuovo repository). L'app costruisce e distribuisce automaticamente la tua documentazione.
Ogni push sul branch configurato avvia automaticamente un deployment. Personalizza la documentazione di partenza quando sei pronto.
Connetti un repository esistente
Installa l'app GitHub di Jamdesk e concedile l'accesso al tuo repository di documentazione. Poi scegli il repository e il branch in Jamdesk in Impostazioni progetto → Repository Git. Il resto funziona allo stesso modo.
Una app, più progetti
Un'unica installazione dell'app GitHub può servire più progetti Jamdesk:
- Installa l'app una sola volta sul tuo account o sulla tua organizzazione
- Collega repository diversi a progetti Jamdesk diversi
- Ogni progetto ha la propria configurazione di branch e percorso
Un amministratore dell'organizzazione installa l'app GitHub una sola volta. Qualsiasi membro del team può poi creare progetti Jamdesk a partire dai repository a cui l'app ha accesso.
Account GitHub personale (livello utente)
Collegare il tuo account GitHub personale associa la tua identità GitHub al tuo profilo Jamdesk. È separato dall'app GitHub.
Cosa fa
- Ti identifica: associa il tuo nome utente GitHub al tuo account Jamdesk
- Attribuisce le build: mostra chi ha avviato ogni deployment
- Visibilità nel team: i colleghi vedono chi ha apportato le modifiche
Perché è necessario
Jamdesk deve associare ogni push a un utente. Senza il tuo account collegato:
- Jamdesk ricorre all'abbinamento tramite indirizzo email
- Se l'email del tuo commit Git è diversa dalla tua email Jamdesk, l'attribuzione fallisce
- La cronologia delle build potrebbe mostrare "Utente sconosciuto" per i tuoi commit
Problema comune: Git usa un'email personale. Il tuo account Jamdesk usa un'email di lavoro. Collega il tuo account GitHub per risolvere l'attribuzione.
Controlla la tua email Git
git config user.email
git config --global user.email "you@company.com"Impostala sull'email del tuo account Jamdesk. Una discrepanza mostra "Utente sconosciuto" nella cronologia delle build.
Come collegare il tuo account
Clicca sul tuo avatar in alto a destra, poi seleziona Impostazioni utente.
Scorri fino alla scheda Account GitHub.
Si apre un popup verso GitHub. Autorizza Jamdesk a leggere il tuo profilo.
Il tuo nome utente GitHub compare nel tuo profilo Jamdesk.
Come funzionano insieme
Pensale come due chiavi separate:
| Chiave | Apre | Di proprietà di |
|---|---|---|
| App GitHub | Accesso ai repository | Progetto/Organizzazione |
| Collegamento personale | La tua identità | Singolo utente |
Esempio di team
Un team di 3 sviluppatori lavora sulla documentazione aziendale:
- L'amministratore installa l'app GitHub sull'organizzazione
- L'amministratore crea un progetto Jamdesk collegato al repository della documentazione
- Ogni sviluppatore collega il proprio account personale
Ora, quando uno sviluppatore esegue il push:
- L'app GitHub permette a Jamdesk di leggere il repository e costruire
- Il collegamento personale identifica chi ha avviato la build
Esempio di sviluppatore singolo
Gli sviluppatori singoli hanno comunque bisogno delle due connessioni:
- App GitHub: collega il tuo repository a Jamdesk
- Collegamento personale: mostra il tuo nome sui tuoi commit nella cronologia delle build
Disconnessione e scollegamento
Ogni azione rimuove un diverso tipo di accesso.
Disconnettere GitHub (Project Settings)
Cosa fa: Rimuove la connessione al repository da un singolo progetto Jamdesk.
Effetti:
- I deployment automatici si fermano per quel progetto
- L'app GitHub rimane installata su GitHub
- Gli altri progetti Jamdesk non sono interessati
- Il collegamento del tuo account personale non è interessato
Quando usarlo: Vuoi collegare un repository diverso o interrompere temporaneamente i deployment.
Come ricollegare: Vai su Impostazioni progetto → Repository Git 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 tuo profilo
- L'attribuzione delle build ricorre all'abbinamento tramite email
- Tutte le connessioni ai repository restano intatte
- L'app GitHub rimane installata
Quando usarlo: Vuoi collegare un account GitHub diverso, o rimuovere la connessione.
Come ricollegare: Vai su Impostazioni utente → Account GitHub → Collega account GitHub.
Disinstallare la GitHub App (su GitHub)
Cosa fa: Rimuove l'accesso di Jamdesk al tuo account GitHub.
Effetti:
- Tutti i progetti Jamdesk che usano questa installazione perdono l'accesso
- I deployment automatici si fermano per tutti i progetti interessati
- I webhook vengono rimossi
- I collegamenti degli account personali non sono interessati
Disinstalla l'app GitHub solo se vuoi rimuovere l'accesso di Jamdesk da tutti i repository. Questo riguarda ogni progetto Jamdesk collegato al tuo account GitHub.
Come disinstallare:
- Vai su Impostazioni GitHub → Applicazioni → App GitHub installate
- Trova "Jamdesk" e clicca su Configura
- Scorri in basso e clicca su Disinstalla
Riferimento rapido
| Azione | Posizione | Ambito | Reversibile? |
|---|---|---|---|
| Disconnetti GitHub | Impostazioni progetto → Repository Git | Singolo progetto | Sì - ricollega in qualsiasi momento |
| Scollega GitHub | Impostazioni utente → Account GitHub | Il tuo account | Sì - ricollega in qualsiasi momento |
| Disinstalla app GitHub | Impostazioni GitHub | Tutti i progetti | Sì - reinstalla |
Risoluzione dei problemi
"Hai già installato Jamdesk?"
Se hai già installato l'app GitHub di Jamdesk, "Installa app GitHub" apre la pagina delle impostazioni di GitHub invece della pagina di installazione. Completa la configurazione lì:
Scorri fino alla sezione Accesso al repository nella pagina delle impostazioni di GitHub.
Se il pulsante Salva è disattivato (grigio), passa da "Tutti i repository" a "Solo repository selezionati", poi torna indietro.
Clicca sul pulsante verde Salva. 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, poi clicca su Riprova.
"Le mie build mostrano 'Unknown user'"
Il tuo account GitHub personale non è collegato. Vai su Impostazioni utente → Collega account GitHub.
"Il repository non viene visualizzato"
L'app GitHub non ha accesso a quel repository. Vai su Impostazioni GitHub, trova Jamdesk e aggiungi il repository.
"Le build non vengono attivate"
- Verifica che il repository sia collegato in Impostazioni progetto → Repository Git
- Controlla di eseguire il push sul branch configurato
- Controlla la consegna dei webhook nelle impostazioni del repository GitHub
Se tutto questo è corretto, chi ha eseguito il push potrebbe non essere membro del progetto. Jamdesk costruisce un push solo se proviene da un membro del progetto. Associa l'autore tramite il suo account GitHub collegato, oppure tramite l'email del commit che corrisponde all'email con cui accede a Jamdesk.
Senza corrispondenza, la build risulta fallita con il motivo indicato. Il proprietario del progetto riceve un'email, al massimo una a settimana per persona. Un push che non modifica nulla nella cartella della documentazione non invia alcuna email.
Invita la persona in Impostazioni progetto → Membri con la sua email di commit. Per accettare deve accedere a Jamdesk con quell'email. Se è già membro, può collegare il proprio account GitHub nelle Impostazioni utente.
"Non riesco ad accedere ai repository dell'organizzazione"
Un amministratore dell'organizzazione deve approvare l'installazione dell'app GitHub. Chiedi al tuo amministratore di installare o approvare Jamdesk nelle impostazioni dell'organizzazione.
"GitHub continua a rimandarmi alla pagina dell'app Jamdesk"
Probabilmente il tuo account GitHub è gestito dall'azienda. GitHub non consente agli account gestiti di installare app su sé stessi. Vedi account GitHub gestiti dall'azienda per la soluzione.