Discourse GitHub

[Discourse]

	Riepilogo	Discourse GitHub Consente allo staff di assegnare badge agli utenti in base ai contributi su GitHub. Consente inoltre agli utenti di creare Linkback GitHub, Permalink e di visualizzare lo stato in tempo reale delle PR nei onebox.
	Guida all’installazione	Questo plugin è integrato nel core di Discourse. Non è necessario installare il plugin separatamente.

Poiché si tratta di un plugin #ufficiale mantenuto dal team di Discourse, le richieste di #supporto, Contribute > Bug, Contribute > UX e Contribute > Feature possono essere avanzate nelle rispettive categorie qui su Meta, taggandole con l’etichetta appropriata del plugin. Clicca su un link qui sotto per iniziare.

 Supporto  Bug  UX  Funzionalità

Funzionalità

Badge GitHub

Assegna badge ai tuoi utenti in base ai contributi su GitHub.

Come usarlo:

1. Abilita github badges enabled in Impostazioni → Plugin.
2. Genera un token di accesso GitHub e incollalo nell’impostazione github linkback access token. Vedi le istruzioni di seguito.
3. Aggiungi uno o più URL dei repository GitHub da scansionare per i contributi all’impostazione sito github badges repos.

Come funziona il conteggio dei badge:

I badge contengono i commit attraverso tutti i repository e, quando un utente contribuisce a più repository, tutti i suoi commit vengono sommati in un totale unico.

Badge per Committer:

Badge	Commit Richiesti
Bronzo	1 commit
Argento	25 commit
Oro	1000 commit

Progressione dei Badge: Man mano che gli utenti accumulano più contributi in uno qualsiasi dei repository tracciati, passano automaticamente ai livelli successivi dei badge. Ad esempio, se un utente fa commit su Repo A e poi su Repo B, entrambi i contributi contano per il totale, consentendogli di passare da Bronzo ad Argento ad Oro.

---

Linkback GitHub

Crea un link da una pull request o da un commit di GitHub a un post di Discourse in cui viene menzionato.

Come usarlo:

1. Abilita github linkback enabled in Impostazioni → Plugin.
2. Genera un token di accesso GitHub e incollalo nell’impostazione github linkback access token. Vedi le istruzioni di seguito.
3. Infine, aggiungi i progetti a cui desideri pubblicare nell’impostazione sito github linkback projects nei formati:
   • username/repository per repository specifici
   • username/* per tutti i repository di un determinato utente

---

Permalink GitHub

Sostituisci i link non permalink di GitHub con permalink.

Come usarlo:

1. Abilita github permalinks enabled in Impostazioni → Plugin.

---

Stato Live PR

Visualizza indicatori di stato in tempo reale sui onebox delle pull request di GitHub nei post e nei messaggi di chat. Lo stato si aggiorna automaticamente tramite webhook quando le PR cambiano su GitHub.

Tipi di Stato

Stato	Colore	Descrizione
Bozza	Grigio	La PR è contrassegnata come bozza
Aperta	Grigio	La PR è aperta e in attesa di revisione
Approvata	Verde	La PR è stata approvata dai revisori
Modifiche Richieste	Arancione	I revisori hanno richiesto modifiche
Unità (Merged)	Viola	La PR è stata unita
Chiusa	Rosso	La PR è stata chiusa senza essere unita

Come usarlo:

Passo 1: Abilita la Funzionalità

Vai su Admin > Impostazioni > Plugin e imposta github pr status enabled su true.

Passo 2: Configura i Token di Accesso GitHub

Per recuperare lo stato delle PR (in particolare per i repository privati), configura i token di accesso GitHub.

Impostazione: github onebox access tokens

Formato:

nome_organizzazione|ghp_tuo_token_qui
predefinito|ghp_token_fallback_qui

Puoi specificare token per organizzazione, oltre a un token predefinito utilizzato come fallback. Ogni riga dovrebbe contenere nome_org|token dove il token è un GitHub Personal Access Token (classico) con ambito repo.

Esempio:

discourse|ghp_xxxxxxxxxxxxxxxxxxxx
mia-azienda|ghp_yyyyyyyyyyyyyyyyyyyy
predefinito|ghp_zzzzzzzzzzzzzzzzzzzzzz

Passo 3: Configura i Webhook GitHub (per Aggiornamenti in Tempo Reale)

Per ottenere aggiornamenti automatici dello stato quando le PR cambiano, configura un webhook su GitHub.

Genera un Segreto Webhook:

openssl rand -hex 32

Imposta l’impostazione sito github webhook secret sul tuo segreto generato.

Crea il Webhook su GitHub:

Puoi creare il webhook a livello di organizzazione (per coprire tutti i repo) o per singolo repository.

Per un’organizzazione:

1. Vai alle Impostazioni della tua organizzazione
2. Naviga verso Webhooks (sotto Codice, pianificazione e automazione)
3. Clicca su Aggiungi webhook

Per un repository:

1. Vai alle Impostazioni del tuo repository
2. Naviga verso Webhooks
3. Clicca su Aggiungi webhook

Configurazione Webhook:

Campo	Valore
URL Payload	https://il-tuo-sito-discourse.com/discourse-github/webhooks/github
Tipo di contenuto	application/json
Segreto	Il tuo segreto webhook generato
Verifica SSL	Abilita (consigliato)
Eventi	Seleziona “Consentimi di selezionare eventi individuali”

Seleziona questi eventi:

• Pull requests
• Pull request reviews

Clicca su Aggiungi webhook per salvare.

Passo 4: Verifica la Configurazione

1. Crea un post di test con un URL PR di GitHub
2. Verifica che il onebox venga visualizzato con un’icona di stato
3. Cambia lo stato della PR su GitHub (ad esempio, approvatala o chiudila)
4. Dopo pochi secondi, aggiorna la pagina di Discourse: lo stato dovrebbe aggiornarsi

Puoi controllare lo stato di consegna del webhook nelle impostazioni webhook di GitHub per confermare che gli eventi vengano inviati e ricevuti con successo.

Priorità dello Stato

Quando una PR ha più stati (ad esempio, approvata ma con modifiche richieste), lo stato è determinato da questa priorità:

1. Unità (Merged) (priorità più alta)
2. Chiusa
3. Bozza
4. Modifiche Richieste
5. Approvata
6. Aperta (predefinita)

Logica dello Stato di Revisione

La funzionalità recupera le informazioni di revisione dall’API GitHub per determinare lo stato di approvazione:

• Prende l’ultima revisione da ogni revisore
• Ignora gli stati di revisione “commentato” e “in attesa”
• Mostra “modifiche richieste” se qualsiasi revisore ha richiesto modifiche
• Mostra “approvata” solo se esistono revisioni e nessuna richiede modifiche

Dove Funziona

• Post del forum — Qualsiasi post contenente un onebox PR di GitHub
• Messaggi di chat — I onebox PR nella chat mostrano anche lo stato in tempo reale

Nota: I onebox inline (quando un link appare inline nel testo invece che come anteprima completa) non mostrano icone di stato.

Migrazione dal Componente Tema GitHub Status

Questa funzionalità sostituisce il componente tema GitHub Status Indicators. I due non sono compatibili e non dovrebbero essere usati insieme.

Se stai attualmente utilizzando il componente tema:

1. Disabilita e rimuovi il componente tema github-status-theme
2. Abilita questa funzionalità integrata tramite l’impostazione github pr status enabled

---

Configurazione

Token di Accesso GitHub

Affinché la funzionalità linkback funzioni e i badge vengano concessi ai tuoi utenti, devi fornire un token di accesso GitHub. Puoi generare il tuo token qui: Sign in to GitHub · GitHub.

La funzionalità linkback richiede l’ambito public_repo, mentre la concessione dei badge non richiede alcun ambito (lascia tutto deselezionato se vuoi solo i badge). Poiché l’ambito public_repo concede accesso in scrittura ai repository, ti consigliamo di creare un account GitHub usa e getta che non ha accesso a nessun repository e di usarlo solo per generare un token.

Ambiti dei Token per Funzionalità

Funzionalità	Ambito Richiesto
Badge	Nessun ambito richiesto
Linkback	public_repo
Stato PR (repo pubblici)	Nessun ambito richiesto
Stato PR (repo privati)	repo

---

Riferimento Impostazioni Sito

Impostazione	Predefinito	Descrizione
enable discourse github plugin	false	Interruttore principale per il plugin
github badges enabled	false	Abilita i badge dei contributi GitHub
github badges repos	(vuoto)	URL dei repository da tracciare per i badge
github linkback enabled	false	Abilita i linkback da GitHub a Discourse
github linkback access token	(vuoto)	Token di accesso per la funzionalità linkback
github linkback projects	(vuoto)	Progetti per cui creare linkback
github permalinks enabled	false	Sostituisci i link GitHub con permalink
github pr status enabled	false	Abilita le icone di stato PR sui onebox
github webhook secret	(vuoto)	Segreto per la verifica della firma webhook
github onebox access tokens	(vuoto)	Token di accesso per l’API GitHub (formato: org|token)

---

Dettagli Tecnici

Utilizzo API Stato PR

Quando viene generato un onebox PR di GitHub, Discourse effettua fino a due chiamate API:

1. Dati PR: GET /repos/{owner}/{repo}/pulls/{number} — Recupera le informazioni di base sulla PR, inclusi stato, stato di unità e stato di bozza
2. Revisioni: GET /repos/{owner}/{repo}/pulls/{number}/reviews — Recupera i dati di revisione per determinare lo stato di approvazione

Queste chiamate utilizzano il tuo token di accesso configurato se disponibile, consentendo l’accesso ai repository privati.

Sicurezza Webhook

Le richieste webhook vengono verificate utilizzando la convalida della firma HMAC-SHA256. GitHub firma il payload del webhook con il tuo segreto e Discourse verifica questa firma prima di elaborarlo. Le firme non valide vengono rifiutate con una risposta 403.

Eventi Webhook che Attivano gli Aggiornamenti

• Modifiche allo stato PR (aperta, chiusa, riaperta)
• PR unita
• Modifiche allo stato di bozza (convertita in bozza, pronta per la revisione)
• Revisioni pull request inviate
• Revisioni modificate o annullate

Considerazioni sulle Prestazioni

• La ribake è accodata come lavoro in background a bassa priorità per evitare di impattare sulle prestazioni del sito
• Solo i post/messaggi con onebox completi PR di GitHub vengono ribake (i onebox inline vengono saltati)
• I ribake dei messaggi di chat saltano le notifiche per evitare avvisi duplicati

---

CHANGELOG

2025-12-10

• FIX: Salta le notifiche quando si ribakano i messaggi di chat dai webhook GitHub

2025-12-09

• FIX: Salta il ribake dei post con onebox PR GitHub inline
• FIX: Evita lo stato intermedio durante il ribake dei post con onebox
• FIX: Ribake i messaggi di chat quando lo stato PR GitHub cambia
• UX: Usa min-height per prevenire lo spostamento del layout quando l’icona di stato cambia
• UX: Riduci le dimensioni dell’icona di stato PR GitHub su mobile

2025-12-08

• FEATURE: Aggiungi lo stato “modifiche richieste” ai onebox PR GitHub

2025-12-04

• FEATURE: Icona di stato live PR GitHub

2025-11-10

• FEATURE: Consenti e nega la lista per i linkback

2025-11-08

• FEATURE: Aggiungi lista di ignorazione categoria per i linkback GitHub

2024-12-20

• DEV: Sposta discourse-github nel core (non richiede più installazione separata)

[ImmaZoni (Justin)]

Qual è il processo per più collegamenti? li aggiunge semplicemente allo stesso commento del commit? o crea un commento completamente nuovo ogni volta?

[satonotdead]

Mi chiedo se i badge di commit e PR potrebbero essere semplificati perché stiamo cercando di evitare Il paradosso della scelta :)\n\nAttualmente ho appena fatto il fork e cancellato i badge di commit ma ovviamente mi sono perso dal badge di commit (perché sto committando direttamente) e il fork non equivale a rimanere sempre con il core.

[xomiamoore (Mia)]

@Discourse

• username/repository per repository specifiche
• username/* per tutti i repository di un certo utente

Il carattere jolly * non ha funzionato per un’organizzazione GitHub, ho finito per inserire ogni repository individualmente. Qualcun altro ha avuto problemi con questo con un’organizzazione rispetto a un utente?

[greyli]

Come impostare la lingua del commento di linkback?

[cultiv (Sebastiaan Janssen)]

Grazie, mi piace molto questo plugin! Ero confuso riguardo al sistema dei badge e sono stato felice di trovare la spiegazione in un altro argomento: Github Badges are not working. Its hard to see if I do something wrong or if the plugin is not working - #4 by simon

Tuttavia, quella risposta osserva che

Il plugin crea 6 badge:

Non vedo nessuno di questi badge, non sono sicuro di cosa sia successo? C’è un modo per (ri)attivare la creazione di questi badge?

[cultiv (Sebastiaan Janssen)]

Per rispondere alla mia domanda, dopo qualche ora l’attività pianificata è stata eseguita e in quel momento sono stati creati i badge.

@cultiv

C’è un modo per (ri)attivare la creazione di questi badge?

Il modo manuale per farlo sarebbe attivare il job sidekiq, a quanto pare.

[tomtjes (Thomas Reintjes)]

Richiesta di funzionalità: escludere categorie e/o tag dai linkback

Abbiamo una categoria Annunci in cui il plugin RSS automaticamente recupera le nuove versioni di GitHub. Quando le note di rilascio collegano a problemi, anche quel link appare su Discourse e viene creato un linkback, ma uno che non è utile a nessuno, creando confusione su Github.

Vorrei poter escludere certi post, cioè categorie o tag o anche solo post dell’utente configurato nel plugin RSS, dal creare linkback.

[david (David Taylor)]

Questo plugin è ora incluso nel core di Discourse come parte di Bundling more popular plugins with Discourse core. Se stai auto-ospitando e utilizzi il plugin, devi rimuoverlo dal tuo app.yml prima del tuo prossimo aggiornamento.