Configura l'integrazione GitHub
Questa guida copre le parti della configurazione specifiche di GitHub. GitHub è uno dei tre host di codice supportati — vedi Collega un host di codice per collegare GitLab o Bitbucket e per capire come uno spazio di lavoro li combina.
Prerequisiti
Sezione intitolata “Prerequisiti”- Un account GitHub con accesso ai repo su cui vuoi lavorare
- Una GitHub App registrata per il tuo server (vedi
Crea la GitHub App) così puoi
accedere, oppure un personal access token con
repoeread:orgda incollare
Accedi con GitHub
Sezione intitolata “Accedi con GitHub”Un device flow: GitHub ti mostra un codice breve, tu lo approvi su github.com e il server riceve la credenziale — nessun URL di callback, nessuna porta, niente da esporre. Disponibile ogni volta che il server ha un client id, che una build ufficiale fornisce già.
- Vai su Impostazioni → Spazio di lavoro → Profilo e identità → Hosting del codice (o al primo passaggio dell’onboarding)
- Sulla riga GitHub, clicca su Accedi con GitHub
- Una finestra di dialogo mostra un codice di otto caratteri e apre github.com/login/device nel tuo browser. Il codice è già negli appunti
- Incollalo, approva l’app e torna qui. La riga diventa da sola «Autenticato come tuo-nome-utente»
Puoi chiudere la finestra di dialogo mentre completi nel browser — il server continua a eseguire il polling finché il codice non scade (circa 15 minuti), quindi l’accesso va comunque a buon fine.
Oppure incolla un token
Sezione intitolata “Oppure incolla un token”La soluzione di ripiego quando il server non ha un’app, quando l’app non è installata su un account che ti serve, o quando preferisci semplicemente usare un PAT.
- Vai su Impostazioni → Spazio di lavoro → Profilo e identità → Hosting del codice
- Sulla riga GitHub, clicca su Aggiungi token
- Incolla un token con
repoeread:org(classico) e salva. Un token fine-grained richiede Contents e Pull requests del repository (in lettura e scrittura), più Checks e Actions (in lettura).
Il token viene verificato mentre viene salvato, così la riga può indicare l’account a cui appartiene. Clicca su Disconnetti per rimuoverlo.
Verifica: la riga GitHub mostra «Autenticato come tuo-nome-utente». Un suffisso indica l’origine quando la credenziale che risponde non è la tua — «tramite l’app di questo server» o «dall’ambiente».
Cosa ti offre l’integrazione
Sezione intitolata “Cosa ti offre l’integrazione”| Funzionalità | Come |
|---|---|
| Elenco e dettaglio delle PR | L’API REST di GitHub, dal server, sull’identità applicativa o sulla tua credenziale |
| Esecuzioni dei controlli | L’API Checks di GitHub |
| Pubblicazione delle revisioni | Un passaggio attivato dall’utente che pubblica la tua revisione sulla PR |
| Registrazione dei repo | Un checkout viene accettato se il suo remote origin punta a github.com — o a gitlab.com / bitbucket.org |
| Accesso GitHub degli agenti | Il broker delle credenziali inietta un token di sola lettura come GH_TOKEN / GITHUB_TOKEN; i push passano da Control Center |
| Ping delle notifiche | Un polling lato server della tua casella delle notifiche GitHub genera «menzionato in una pull request» e «revisione richiesta» |
| Profili utente | Schede del profilo al passaggio del mouse e filtro delle PR per autore |
Alcuni percorsi usano l’API GraphQL invece di REST dove costa meno — l’attività dei branch per il selettore di composizione delle PR e lo stato di revisione in tempo reale che decide se una notifica di revisione richiesta è ancora in sospeso.
Tieni d’occhio i guasti di GitHub
Sezione intitolata “Tieni d’occhio i guasti di GitHub”La barra del titolo mostra un chip di stato quando un provider è degradato, e copre GitHub, Claude, OpenAI e Kimi. È nascosto finché tutto è sano — la presenza segnala un problema, non la sua assenza.
Clicca sul chip per aprire un flyout con lo stato di ogni provider e un pulsante di aggiornamento. Gli stati si aggiornano da soli ogni due minuti.
Sapere come agiscono gli agenti su GitHub
Sezione intitolata “Sapere come agiscono gli agenti su GitHub”- Un agente che lavora in un worktree GitHub riceve sempre un token GitHub di sola lettura. Un push passa da Control Center, che interroga la regola Eseguire il push a un remoto e poi lo inoltra con un token di scrittura che l’agente non possiede mai. Vedi Configura le policy del sandbox
- I commit creati da un agente sono attribuiti all’agente — il nome
visualizzato più
(agent), a un indirizzo sintetico derivato dall’id dell’agente — mai a una persona. Chi ha fatto la richiesta viene accreditato con un trailerCo-Authored-By - Con una GitHub App configurata, il broker conia token di installazione
fine-grained, limitati al repo e di circa un’ora per ogni avvio, invece di
consegnare un token ampio. L’installazione viene risolta dal proprietario
del repo dell’esecuzione, quindi un’unica app installata su più account si
limita correttamente a quello che l’esecuzione tocca. Senza un’app, gli agenti
ricevono il token dell’ambiente, che non può essere limitato alla sola
lettura: la regola di push vincola allora
git push, ma non il codice che usa direttamente il token - Il token è sempre quello del broker, mai quello del membro richiedente. Il token del server viene trattenuto a un’esecuzione che agisce per un membro che non è il proprietario e non ha collegato GitHub
Risoluzione dei problemi
Sezione intitolata “Risoluzione dei problemi”L’elenco delle PR è vuoto e dice che GitHub non è collegato
Sezione intitolata “L’elenco delle PR è vuoto e dice che GitHub non è collegato”Non hai alcuna credenziale GitHub su questo server. Accedi o incolla un token in Hosting del codice. I repo su altri forge non sono interessati — solo quelli di GitHub non contribuiscono nulla.
La riga offre «Aggiungi token» ma non «Accedi con GitHub»
Sezione intitolata “La riga offre «Aggiungi token» ma non «Accedi con GitHub»”Il server non ha un client id — che è lo stato normale per una build dal codice sorgente, dato che le credenziali vengono incorporate solo nelle build ufficiali. Vedi Crea la GitHub App: richiede circa due minuti e solo il proprietario del server deve farlo, una volta sola.
La finestra di accesso dice che il provider non ha restituito alcun device code
Sezione intitolata “La finestra di accesso dice che il provider non ha restituito alcun device code”La GitHub App esiste, ma la sua casella Device flow è disattivata. Attivala nelle impostazioni dell’app (General → Device flow) e riprova.
La riga dice «tramite l’app di questo server» quando mi aspettavo il mio account
Sezione intitolata “La riga dice «tramite l’app di questo server» quando mi aspettavo il mio account”Non hai effettuato l’accesso; quello che vedi è l’identità applicativa del server che risponde. Clicca su Accedi con GitHub su quella riga.
Un PAT fine-grained non mostra il pulsante di unione né lo stato dei controlli
Sezione intitolata “Un PAT fine-grained non mostra il pulsante di unione né lo stato dei controlli”Il token richiede Contents e Pull requests (in lettura e scrittura), più Checks e Actions (in lettura). Dopo averlo modificato, incollalo di nuovo in Hosting del codice.
L’aggiunta di un repo viene rifiutata
Sezione intitolata “L’aggiunta di un repo viene rifiutata”La registrazione richiede tutte e tre le condizioni: il percorso è dentro un git
work tree, ha un remote origin e quel remote punta a un forge supportato
(github.com, gitlab.com o bitbucket.org). Vedi
Aggiungi repo a uno spazio di lavoro.
Tutto smette di funzionare per un po’ dopo un uso intenso
Sezione intitolata “Tutto smette di funzionare per un po’ dopo un uso intenso”È l’interruttore di circuito del rate limit. GitHub segnala il suo limite primario
con un 403 che porta x-ratelimit-remaining: 0 e un orario di reset;
vedendone uno, il client fa fallire localmente le richieste successive senza una
chiamata di rete finché la finestra non trascorre, così una tempesta di tentativi
non può aggravare il limite. I guasti transitori vengono ritentati fino a tre
volte con backoff esponenziale, rispettando retry-after.