Crea la GitHub App

Questa guida mostra come dare al tuo server una propria identità GitHub. Richiede circa due minuti, la esegue solo il proprietario del server e va fatta una sola volta per server.

Per collegare in seguito il tuo account, vedi Configura l’integrazione GitHub.

Perché il tuo server ha bisogno di un’app propria

Una sola registrazione produce due compiti diversi, ed è l’app che li rende entrambi onesti:

Compito	Cosa risponde	Perché conta
Una persona accede	L’id client dell’app, tramite il flusso dispositivo	Ottieni una credenziale che è tua, sul server, su ogni dispositivo — senza token da incollare o da ruotare
Il server agisce	L’id dell’app + la chiave privata → token di installazione	Webhook, polling delle PR e sincronizzazione dei ticket smettono di dipendere dalla validità del token di una persona

Nota cosa non c’è in questa tabella: un segreto client. Il flusso dispositivo di GitHub si autentica con il solo id client — sia la richiesta del codice dispositivo sia il polling del token — quindi non c’è alcun segreto da conservare per accedere.

Senza un’app propria, il primo compito funziona comunque tramite l’id client fornito dalla build; il secondo ricade sulle credenziali del proprietario del server, quindi il lavoro in background si appoggia su chi ha configurato il server per primo.

Prerequisiti

Sei il proprietario del server — le operazioni providerApps.* sono riservate a lui, e la scheda è invisibile a tutti gli altri
Un account GitHub, o un’organizzazione in cui puoi creare app
Nulla raggiungibile pubblicamente: l’accesso è un flusso dispositivo, quindi il server non ha bisogno di porte in ingresso, tunnel, URL di callback o dominio

Registra l’app

Vai su github.com/settings/apps/new (per un’organizzazione: Settings → Developer settings → GitHub Apps → New GitHub App)
GitHub App name — qualsiasi cosa; Control Center (yourname) va bene. Compare nei commit e nei commenti creati dal server
Homepage URL — qualsiasi cosa, ad es. https://github.com/your-name
Callback URL — lascialo vuoto. Il flusso dispositivo non ne ha
Seleziona Enable Device Flow. È l’unica impostazione senza la quale l’accesso non può funzionare
Deseleziona Webhook → Active a meno che tu non stia configurando i webhook separatamente
Sotto Repository permissions, concedi almeno:
- Contents: Read and write
- Metadata: Read-only (obbligatorio)
- Pull requests: Read and write
- Issues: Read and write, se usi GitHub Issues per i ticket, e per la ricerca dei commenti del bot nelle conversazioni delle PR (vedi Parla con Control Center da una PR GitHub)
- Checks: Read-only, per lo stato della CI nella pagina della PR
Sotto Where can this GitHub App be installed?, scegli l’opzione adatta — «Only on this account» è quella giusta per un server personale
Fai clic su Create GitHub App

Raccogli i tre valori

Nella pagina dell’app, subito dopo la creazione:

Valore	Dove
App ID	La scheda General, in alto
Client ID	La scheda General, sotto «Client secrets»
Private key	Generate a private key — scarica un file `.pem`

Il file della chiave privata si scarica una sola volta e GitHub non lo mostra mai più. Conservalo finché non l’hai incollato; puoi sempre generarne un altro.

Il segreto client è facoltativo e serve esattamente a una cosa: se lasci attiva l’opzione «Expire user authorization tokens», è ciò che rinnova silenziosamente il token di una persona invece di chiederle di accedere di nuovo ogni otto ore. L’accesso in sé non lo usa mai.

La configurazione più semplice è disattivare quella scadenza: così non serve più alcun segreto. Se la lasci attiva, genera un segreto e incollalo in Impostazioni → Server → Accesso single sign-on (la scheda App del fornitore) — non esiste una variabile d’ambiente per esso, e nessuna è incorporata in una build, quindi resta sul tuo server.

Installala sul tuo account

Un’app registrata ma non installata può autenticare le persone e non leggere nulla.

Nella pagina dell’app, apri Install App
Installala sul tuo account o sulla tua organizzazione
Scegli All repositories, oppure seleziona quelli che questo server deve vedere

Incollala in Control Center

Vai in Impostazioni → Server → Accesso single sign-on e scorri fino alla scheda App del fornitore
Nel blocco GitHub, imposta ogni campo:
- Id app — l’App ID numerico
- Chiave privata — incolla l’intero file .pem, righe BEGIN e END incluse
- Id client — dalla stessa pagina
- Segreto client — solo se ne hai generato uno (per il rinnovo del token)
Fai clic su Test

La chiave viene analizzata nel momento in cui viene salvata, quindi un incolla troncato o con un formato errato viene rifiutato subito, invece di fallire ore dopo su una richiesta in background. Test va oltre e chiede a GitHub su quali account è installata l’app — «salvato» e «funziona» sono due affermazioni diverse, e solo la seconda significa che qualcosa verrà eseguito.

Punto di verifica: il blocco GitHub mostra «Il server può agire per conto proprio e le persone possono accedere», e la riga GitHub sotto Impostazioni → Spazio di lavoro → Profilo e identità → Hosting del codice ora offre Accedi con GitHub.

Configurala invece con variabili d’ambiente

Per un’installazione headless o automatizzata, il server inizializza ogni campo dall’ambiente la prima volta che non ha un valore memorizzato:

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="$(cat control-center.private-key.pem)"
GITHUB_CLIENT_ID=Iv1.0123456789abcdef

Non esistono flag da riga di comando per questi valori — un segreto sulla riga di comando è leggibile da ogni processo dell’host tramite ps. L’ambiente è l’unico posto dove configurarli, e ha la precedenza su ciò che fornisce la build. .env.template è l’elenco completo.

Per lo sviluppo locale, il file .env alla radice del repository contiene gli stessi valori e l’app desktop li passa al server che avvia. Metti la chiave su una sola riga: un valore di .env occupa una riga, e \n tra virgolette doppie viene decodificato in un carattere di nuova riga.

GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEow…\n-----END RSA PRIVATE KEY-----"

GITHUB_APP_ID e GITHUB_APP_PRIVATE_KEY sono gli stessi nomi che il broker di token della sandbox legge già, quindi un host che ha configurato token agente con granularità fine ottiene gratis la corsia dell’accesso. L’inizializzazione avviene una volta per campo — dopodiché vince il valore memorizzato, quindi una modifica fatta nelle Impostazioni non viene annullata al riavvio successivo.

Fai lo stesso per Linear

Linear non ha un flusso dispositivo, quindi il suo accesso fa un passaggio nel browser e richiede davvero un URL di callback — la scheda App del fornitore ti mostra esattamente quello da registrare.

Crea un’applicazione OAuth su linear.app/settings/api/applications/new
Imposta l’URL di callback sull’URL mostrato dalla scheda, testualmente
Incolla l’Id client e il Segreto client nel blocco Linear
Facoltativamente aggiungi una Chiave API dello spazio di lavoro — è la credenziale che il server usa per sincronizzare i ticket quando nessuna persona l’ha richiesto

Risoluzione dei problemi

La finestra di accesso dice che il fornitore non ha restituito alcun codice dispositivo

Enable Device Flow è disattivata nell’app. Attivala sotto General e riprova.

Il test dice che le credenziali funzionano, ma l’app non è installata da nessuna parte

Registrazione e installazione sono due passaggi distinti. Apri Install App nella pagina dell’app e installala.

Il test dice che non è stato possibile leggere la chiave privata

Incolla l’intero file .pem, comprese le righe -----BEGIN e -----END. Una chiave ed25519 o EC non può essere usata — le GitHub App firmano con RSA.

Un membro ha effettuato l’accesso ma non vede alcun repository

L’app non è installata sull’account che li possiede, oppure la sua installazione seleziona repository diversi. Il suo accesso personale concede solo ciò che l’app è autorizzata a vedere.