Che cosa sono le app GitHub?

• 10 minuti

In questa unità verrà illustrato che cosa sono le app GitHub, come funzionano e come è possibile 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. Viene esposta tramite gli endpoint REST, quindi è facile integrarla da 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 verranno presentate le app GitHub e le app OAuth, le rispettive differenze a livello di utilizzo e autorizzazione e le sottoscrizioni di eventi.

Quando si personalizza un flusso di lavoro di GitHub, sono disponibili diverse funzionalità, ad esempio la scrittura di script personalizzati, la creazione e l'autorizzazione di app OAuth personalizzate o l'installazione di app GitHub disponibili in GitHub Marketplace. In generale, è consigliabile usare gli script per queste attività occasionali. Per le azioni che devono essere eseguite più spesso, è possibile usare l'automazione delle app OAuth e delle app GitHub per consentire all'utente e al team di risparmiare tempo e mantenere 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 si avrà una buona comprensione delle differenze tra un'app GitHub e un'app OAuth e si saprà come scegliere nel modo migliore un'app per la situazione giusta.

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 possono essere facilmente considerate attendibili, mentre altre potrebbero essere sospette. Assicurarsi sempre di avere familiarità con le autorizzazioni concesse a un'app.

app OAuth

Le app OAuth consentono di accedere ai dati di GitHub per conto di un utente. Poiché l'app agisce per conto dell'utente, è importante notare che utilizzerà una postazione di GitHub con licenza. È 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 divulgherà il tipo di accesso necessario all'organizzazione o al repository. Gli utenti autorizzano le app OAuth e ciò consente all'app di fungere da utente autenticato, ad esempio per leggere o modificare i 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, ma l'app OAuth ottiene anche l'accesso a tutte le risorse disponibili per l'utente.

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

Le app GitHub, invece, vengono installate nell'account personale, nelle organizzazioni di cui si è proprietari o in repository specifici a cui si può accedere come amministratore. Le app GitHub vengono installate e interagiscono con GitHub come servizio, non come utente individuale, come nel caso delle app OAuth. Uno dei vantaggi delle app GitHub rispetto alle app OAuth consiste nel fatto che le app GitHub non utilizzano alcuna postazione di GitHub con licenza.

Le app GitHub accedono ai dati per conto dell'applicazione stessa tramite una chiave privata usata per firmare un token JWT (JSON Web Token). Poiché vengono installate in repository specifici, gli utenti possono scegliere a quali repository l'app può accedere, in modo da limitare la quantità di dati accessibili per l'app. 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. Ciò consente di concedere autorizzazioni più granulari, limitando l'app alla lettura e scrittura solo nei repository a cui è autorizzata ad accedere. 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 cercano app GitHub, occorre ricordare che alcune app hanno un badge di tipo Verificato. Questo badge indica che l'app è di proprietà di un'organizzazione che ha verificato la proprietà del rispettivo dominio, ha confermato il proprio indirizzo e-mail con il supporto di GitHub e richiede l'autenticazione a due fattori per l'organizzazione.

• Un amministratore può concedere autorizzazioni relativi ad amministrazione del repository, controlli, contenuti dei repository, distribuzioni e problemi. Le modifiche dell'amministratore richiedono l'accettazione da parte 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, 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

Benché le app GitHub siano un ottimo modo per eseguire l'integrazione nel flusso di lavoro in alcune situazioni, può risultare difficile per organizzazioni di grandi dimensioni eseguire la transizione dall'uso tradizionale delle app OAuth per l'automazione. Una restrizione dei criteri di sicurezza, ad esempio, può limitare anche le opzioni di un amministratore nello scegliere di usare questi strumenti.

Per determinare quale app è la soluzione giusta per la situazione specifica, ecco alcune importanti domande da considerare:

• L'app deve fungere da utente?
• Quale dovrà essere il limite di frequenza?
• 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 hanno autorizzazioni mirate che consentono 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 può accedere solo ai repository concessi da un proprietario dell'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. Si tratta dello stesso flusso usato nell'autorizzazione da utente a server dell'app GitHub.
Le app GitHub chiedono l'autorizzazione per i contenuti del repository e usano il token di installazione per l'autenticazione tramite Git basato su HTTP.	Le app OAuth chiedono l'ambito write:public_key e l'opzione Create a deploy key 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 possono essere facilmente considerate attendibili, mentre altre potrebbero essere sospette. Assicurarsi sempre di avere familiarità con le autorizzazioni concesse a un'app.

La decisione relativa all'uso di un'app GitHub o un'app OAuth può dipendere dal livello di accesso che si vuole assegnare all'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 i dettagli relativi alla risposta da adottare quando viene rilevata 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.

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, questo viene generato immediatamente. 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.

Polling

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 consiste nell'usare un servizio di invio dei webhook, ad esempio smee.io. Con questo approccio, il servizio pubblico effettuerà la sottoscrizione al webhook del repository e quindi inoltrerà i dati in arrivo 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.