Che cosa sono le app GitHub?
In questa sezione viene illustrato cosa sono le app GitHub, come funzionano e come usarle per migliorare i flussi di lavoro. È sempre possibile migliorare i processi, sia quando si adotta una soluzione creata da altri che quando si sviluppa una soluzione per soddisfare le proprie esigenze specifiche.
Estendere la piattaforma tramite l'API GitHub
GitHub fornisce un'API solida che consente agli sviluppatori di eseguire praticamente qualsiasi operazione sulla piattaforma. L'API viene esposta tramite endpoint REST, quindi è facile da integrare con qualsiasi piattaforma o linguaggio di programmazione. Tuttavia, l'accesso all'API tuttavia non è autonomo. Gli sviluppatori che vogliono condividere le funzionalità con gli altri devono ancora inserirla in un pacchetto come app e pubblicarla prima che chiunque possa usarla.
Esistono diversi fattori da considerare quando si sceglie tra incorporare un'app OAuth o un'app GitHub nel flusso di lavoro. In questa sezione vengono presentate le app GitHub e le app OAuth, le differenze di utilizzo e autorizzazione e le sottoscrizioni di eventi.
Quando si personalizza un flusso di lavoro GitHub, sono disponibili diverse funzionalità. Ad esempio, la scrittura di script personalizzati, la creazione e l'autorizzazione delle app OAuth o l'installazione di App GitHub disponibili nel marketplace GitHub. In generale, è consigliabile usare gli script per queste attività occasionali. Per le azioni eseguite più spesso, l'automazione di OAuth e GitHub Apps può aiutare l'utente e il team a risparmiare tempo, mantenendo al tempo stesso il livello ottimale di sicurezza all'interno dei flussi di lavoro. Esistono molte differenze che influiscono sul modo in cui si decide di usare un'app GitHub o un'app OAuth. Il riconoscimento anticipato di queste differenze può ridurre le complessità e le rielaborazioni nelle fasi successive e può consentire di trovare l'applicazione migliore per il caso d'uso specifico nel flusso di lavoro.
Alla fine di questa sezione è necessario avere una buona conoscenza delle differenze tra un'app GitHub e un'app OAuth e sapere come scegliere al meglio un'app per la situazione corretta.
Concessione dell'accesso e delle autorizzazioni
Uno degli aspetti più importanti da considerare per consentire a un'app di accedere a un repository GitHub sono le autorizzazioni necessarie. Alcune app sono facili da considerare attendibili, ma altre potrebbero essere sospette. Assicurarsi sempre di avere familiarità con le autorizzazioni concesse a un'app.
Nota
Ogni app usa una chiave API univoca per richiedere i dati nel repository. Quando si autorizza l'accesso, di fatto è la chiave che viene autorizzata. È possibile revocare l'accesso alla chiave di un'app in qualsiasi momento dalle impostazioni del repository.
app OAuth
Le app OAuth consentono di accedere ai dati di GitHub per conto di un utente. Poiché agisce per conto dell'utente, è importante notare che usa una licenza GitHub. È possibile creare e registrare un'app OAuth nell'account personale o a livello di organizzazione se si ha accesso amministrativo. Un'app OAuth che si integra con GitHub rivela il tipo di accesso all'organizzazione o al repository richiesto. Gli utenti autorizzano le app OAuth, che offrono all'app la possibilità di agire come utente autenticato, ad esempio la lettura o la modifica dei dati. Questo approccio è essenzialmente un modo automatizzato per leggere, scrivere o modificare dati di GitHub come un utente. È anche importante notare che l'autorizzazione è limitata alle risorse accessibili all'utente. Tuttavia, l'app OAuth ottiene anche l'accesso a tutte le risorse disponibili per l'utente.
Nota
Il livello di accesso è limitato dall'ambito del token (utente, organizzazione, repository).
Per le organizzazioni con restrizioni di accesso alle app OAuth, l'amministratore può concedere l'approvazione per l'uso dell'applicazione. Con le sottoscrizioni di eventi, le app OAuth rispondono alle attività non appena si verificano.
App GitHub
Al contrario, Le app GitHub vengono installate nell'account personale, nelle organizzazioni di cui si è proprietari o in repository specifici in cui si dispone dell'accesso amministratore. Le app GitHub vengono installate e interagiscono con GitHub come servizio, non come utente individuale, come nel caso delle app OAuth. Un vantaggio delle app GitHub è che, a differenza delle app OAuth, le app GitHub non usano una licenza GitHub.
GitHub Apps accede ai dati per conto dell'applicazione stessa tramite una chiave privata usata per firmare un token Web JSON. Poiché vengono installati in repository specifici, gli utenti possono scegliere i repository a cui l'app può accedere, che limita la quantità di dati a cui l'app è in grado di accedere. Le autorizzazioni definiscono le risorse a cui l'app GitHub può accedere tramite l'API. A differenza delle app OAuth, le app GitHub hanno autorizzazioni personalizzabili per dati dei repository, problemi e richieste pull. La personalizzazione consente di concedere autorizzazioni più granulari, limitando l'app alla lettura e alla scrittura solo nei repository a cui è consentito l'accesso. Solo i proprietari dell'organizzazione possono gestire l'impostazione delle app GitHub in un'organizzazione.
È possibile trovare e installare app GitHub da GitHub Marketplace. Quando si cerca GitHub Apps, tenere presente che alcune app hanno una notifica verificata. Un badge verificato indica quanto segue sull'app e sull'organizzazione proprietaria:
- La proprietà del dominio dell'organizzazione viene verificata.
- Il supporto di GitHub conferma gli indirizzi di posta elettronica per l'organizzazione.
- L'organizzazione richiede l'autenticazione a due fattori.
- Un amministratore può concedere autorizzazioni per l'amministrazione del repository, i controlli, il contenuto del repository, le distribuzioni e i problemi (le modifiche dell'amministratore richiedono l'accettazione dell'utente)
- Un amministratore può concedere all'utente dell'app le autorizzazioni per bloccare un altro utente, messaggi e-mail, follower, chiavi GPG, chiavi SSH Git, l'assegnazione di stelle e la visualizzazione. Le modifiche dell'amministratore richiedono l'accettazione da parte dell'utente.
- Sottoscrizioni di eventi: avviso di sicurezza, gruppo di controlli, creazione, distribuzione, fork, etichetta, membro, archiviazione, commento del commit, eliminazione, stato della distribuzione, attività cardine, appartenenza, organizzazione. L'amministratore esegue la configurazione nell'interfaccia utente delle app GitHub ed è possibile apportare modifiche.
Scegliere tra app GitHub e app OAuth
Sebbene GitHub Apps sia un modo ideale per l'integrazione nel flusso di lavoro in alcune situazioni, le organizzazioni di grandi dimensioni possono trovare difficile eseguire la transizione dall'uso tradizionale di app OAuth per l'automazione. Ad esempio, una restrizione dei criteri di sicurezza potrebbe anche limitare le opzioni di un amministratore nella scelta di usare questi strumenti.
Nota
L'amministratore di sistema deve collaborare con gli sviluppatori per trovare le opzioni più adatte per l'automazione usando queste applicazioni pur seguendo i criteri di sicurezza.
Per determinare quale app è la soluzione giusta per la situazione specifica, ecco alcune importanti domande da considerare:
- L'app deve fungere da utente?
- Che cosa deve essere il limite di velocità?
- Che livello di accesso si vuole concedere all'app per l'organizzazione e i repository?
- Questa app è conforme ai criteri di sicurezza?
Di seguito sono riportate alcune caratteristiche e differenze essenziali da valutare quando si sceglie tra un'app GitHub o un'app OAuth.
| App GitHub | app OAuth |
|---|---|
| L'installazione di un'app GitHub concede all'app l'accesso ai repository scelti dall'accesso dell'utente o dell'organizzazione. | L'autorizzazione di un'app OAuth concede all'app l'accesso alle risorse accessibili dell'utente, ad esempio i repository a cui è autorizzato ad accedere. |
| I token di accesso dell'installazione sono limitati ai repository specificati con le autorizzazioni scelte dall'autore dell'app. | Un token di accesso OAuth è limitato tramite ambiti. |
| Un token di installazione identifica l'app come bot dell'app GitHub. | Un token di accesso identifica l'app come l'utente che ha concesso il token all'app. |
| Le app GitHub usano autorizzazioni mirate che consentono loro di richiedere l'accesso solo a ciò di cui hanno bisogno. | Le app OAuth non possono usare autorizzazioni granulari. |
| La app GitHub non sono soggette ai criteri dell'applicazione dell'organizzazione. Un'app GitHub ha accesso solo ai repository concessi dal proprietario di un'organizzazione. | Se i criteri di un'applicazione dell'organizzazione sono attivi, solo il proprietario dell'organizzazione può autorizzare l'installazione di un'app OAuth. Se installata, l'app OAuth ottiene l'accesso a qualsiasi elemento visibile al token disponibile per il proprietario dell'organizzazione all'interno dell'organizzazione approvata. |
| Gli aumenti del limite di frequenza possono essere concessi sia a livello di app GitHub (che interessa tutte le installazioni) che a livello di singola installazione. | Gli aumenti del limite di frequenza vengono concessi per ogni app OAuth. Ogni token concesso a tale app OAuth ottiene il limite incrementato. |
| Le app GitHub possono eseguire l'autenticazione per conto dell'utente. Questo approccio viene definito richieste da utente a server. Il flusso da autorizzare corrisponde al flusso di autorizzazione dell'app OAuth. I token da utente a server possono scadere ed essere rinnovati con un token di aggiornamento. | Il flusso OAuth usato dalle app OAuth autorizza un'app OAuth per conto dell'utente. Questo flusso è lo stesso usato nell'autorizzazione da utente a server dell'app GitHub. |
| GitHub Apps richiede l'autorizzazione per il contenuto del repository e usa il token di installazione per l'autenticazione tramite Git basato su HTTP. | Le app OAuth chiedono l'ambito write:public_key e l'opzione Crea una chiave di distribuzione tramite l'API. È quindi possibile usare tale chiave per eseguire i comandi Git. |
Accesso e autorizzazioni per le applicazioni
Uno degli aspetti più importanti da considerare per consentire a un'app di accedere a un repository GitHub sono le autorizzazioni necessarie. Alcune app sono facili da considerare attendibili, ma altre potrebbero essere sospette. Assicurarsi sempre di avere familiarità con le autorizzazioni concesse a un'app.
Prendere la decisione di usare un'app GitHub o un'app OAuth può dipendere dal livello di accesso a cui si vuole accedere l'app. In generale, è consigliabile invitare il team a usare lo strumento con l'ambito più piccolo per eseguire l'attività. Un'app OAuth ha accesso a tutte le risorse di un utente o di un proprietario dell'organizzazione.
- Le app OAuth possono avere accesso in lettura o scrittura ai dati di GitHub
- È possibile concedere a un'app GitHub l'accesso a un account senza che venga concesso l'accesso a un altro account
Sicurezza delle applicazioni
Quando viene trovata una vulnerabilità nell'applicazione, la segnalazione agli utenti del progetto deve essere una priorità inclusa nei criteri di sicurezza. La comunicazione rapida di un problema di sicurezza potrebbe costituire la differenza tra la possibilità della revoca di un token compromesso da parte degli utenti o l'esposizione di dati sensibili. Benché i token siano molto più sicuri delle password, la sicurezza può essere comunque compromessa ed è importante che l'organizzazione sia preparata.
Oltre a un file README.md, è consigliabile aggiungere un file SECURITY.md ai repository. Il file SECURITY.md evidenzia le informazioni correlate alla sicurezza per il repository. Il file deve includere i contatti di sicurezza, i criteri dell'organizzazione e descrive in dettaglio la risposta che si intende adottare quando viene individuata una vulnerabilità.
Reazione agli eventi
Le app GitHub sono progettate per essere passive. Attendono che si verifichi un evento e quindi reagiscono, in genere tramite l'API GitHub. Quando si è in attesa che si verifichino eventi in GitHub, sono possibili due approcci: i webhook e il polling.
Nota
Le app GitHub non sono limitate all'uso dei dati GitHub. È possibile attendere facilmente gli eventi che si verificano da altre origini o eseguire azioni che aggiornano altri servizi.
Uso dei webhook GitHub
I webhook sono l'approccio preferibile per gestire gli eventi. Quando si verifica un evento in GitHub nell'ambito di un webhook, viene generato immediatamente un evento. I webhook effettuano il push di notifiche che l'app può ascoltare ed elaborare in tempo reale. È possibile configurare i webhook nelle impostazioni del repository, inclusi i tipi di eventi, l'autenticazione e il modo in cui vengono recapitate le notifiche HTTP.
Sondaggio
A volte i webhook non sono un'opzione valida. L'app potrebbe trovarsi dietro un firewall aziendale dove non può essere raggiunta direttamente da GitHub. In tal caso, un'alternativa consiste nell'eseguire tramite l'API GitHub il polling dei dati di cui si sta tenendo traccia.
Inoltro dei webhook
Un'alternativa al polling per le app protette da un firewall è utilizzare un servizio di inoltro webhook, come smee.io. Con questo approccio, il servizio pubblico sottoscrive il webhook del repository, quindi inoltra i dati in ingresso a un servizio client in esecuzione dietro il firewall. Il servizio client esegue quindi il push delle notifiche all'app in esecuzione come se provenissero dall'origine iniziale.