Discourse GitHub

[Discourse]

	Resumo	Discourse GitHub Permite que a equipe atribua insígnias aos usuários com base nas contribuições do GitHub. Também permite que os usuários criem Linkbacks do GitHub, Permalinks e exibam o status ao vivo de PRs nos oneboxes.
	Guia de Instalação	Este plugin está embutido no núcleo do Discourse. Não há necessidade de instalar o plugin separadamente.

Como este é um plugin #oficial mantido pela equipe do Discourse, #suporte, #contribuir:bug, #contribuir:ux e #contribuir:feature podem ser solicitados nas respectivas categorias aqui no Meta, e marcados com a tag apropriada do plugin. Clique em um dos links abaixo para começar.

 Suporte  Bug  UX  Recurso

Recursos

Insígnias do GitHub

Atribua insígnias aos seus usuários com base nas contribuições do GitHub.

Como usar:

1. Ative github badges enabled em Configurações → Plugins.
2. Gere um token de acesso do GitHub e cole-o na configuração github linkback access token. Veja as instruções abaixo.
3. Adicione uma ou mais URLs dos repositórios do GitHub para escanear contribuições na configuração do site github badges repos.

Como funciona a contagem de insígnias:

As insígnias contam commits em todos os repositórios, e quando um usuário contribui para vários repositórios, todos os seus commits são somados em uma contagem total.

Insígnias de Committer:

Insígnia	Commits Necessários
Bronze	1 commit
Prata	25 commits
Ouro	1000 commits

Progressão de Insígnias: À medida que os usuários acumulam mais contribuições em qualquer um dos repositórios rastreados, eles avançam automaticamente pelas camadas de insígnias. Por exemplo, se um usuário fizer um commit no Repo A e depois no Repo B, ambas as contribuições contam para o total, permitindo que ele avance de Bronze para Prata e depois para Ouro.

---

Linkback do GitHub

Crie um link de um pull request ou commit do GitHub de volta para uma postagem no Discourse onde ele foi mencionado.

Como usar:

1. Ative github linkback enabled em Configurações → Plugins.
2. Gere um token de acesso do GitHub e cole-o na configuração github linkback access token. Veja as instruções abaixo.
3. Por fim, adicione os projetos nos quais você deseja postar na configuração do site github linkback projects nos formatos:
   • usuario/repositório para repositórios específicos
   • usuario/* para todos os repositórios de um determinado usuário

---

Permalink do GitHub

Substitua os links não permanentes do GitHub por permalinks.

Como usar:

1. Ative github permalinks enabled em Configurações → Plugins.

---

Status ao Vivo de PRs

Exiba indicadores de status ao vivo nos oneboxes de pull requests do GitHub em postagens e mensagens de chat. O status é atualizado automaticamente via webhooks quando os PRs são alterados no GitHub.

Tipos de Status

Status	Cor	Descrição
Rascunho	Cinza	O PR está marcado como rascunho
Aberto	Cinza	O PR está aberto e aguardando revisão
Aprovado	Verde	O PR foi aprovado pelos revisores
Alterações Solicitadas	Laranja	Os revisores solicitaram alterações
Mesclado	Roxo	O PR foi mesclado
Fechado	Vermelho	O PR foi fechado sem mesclagem

Como usar:

Passo 1: Ativar o Recurso

Vá para Admin > Configurações > Plugins e defina github pr status enabled como true.

Passo 2: Configurar Tokens de Acesso do GitHub

Para buscar o status dos PRs (especialmente para repositórios privados), configure os tokens de acesso do GitHub.

Configuração: github onebox access tokens

Formato:

nome_da_organizacao|ghp_seu_token_aqui
padrao|ghp_token_fallback_aqui

Você pode especificar tokens por organização, além de um token padrao usado como fallback. Cada linha deve conter nome_org|token onde o token é um GitHub Personal Access Token (clássico) com escopo repo.

Exemplo:

discourse|ghp_xxxxxxxxxxxxxxxxxxxx
minha-empresa|ghp_yyyyyyyyyyyyyyyyyyyy
padrao|ghp_zzzzzzzzzzzzzzzzzzzzzz

Passo 3: Configurar Webhooks do GitHub (para Atualizações em Tempo Real)

Para obter atualizações automáticas de status quando os PRs forem alterados, configure um webhook no GitHub.

Gerar um Segredo de Webhook:

openssl rand -hex 32

Defina a configuração do site github webhook secret para o segredo gerado.

Criar o Webhook no GitHub:

Você pode criar o webhook no nível da organização (para cobrir todos os repositórios) ou por repositório.

Para uma organização:

1. Vá para as Configurações da sua organização
2. Navegue até Webhooks (sob Código, planejamento e automação)
3. Clique em Adicionar webhook

Para um repositório:

1. Vá para as Configurações do seu repositório
2. Navegue até Webhooks
3. Clique em Adicionar webhook

Configuração do Webhook:

Campo	Valor
URL de Payload	https://seu-site-discourse.com/discourse-github/webhooks/github
Tipo de conteúdo	application/json
Segredo	O segredo do webhook gerado
Verificação SSL	Ativar (recomendado)
Eventos	Selecione “Permitir que eu selecione eventos individuais”

Selecione estes eventos:

• Pull requests
• Revisões de pull request

Clique em Adicionar webhook para salvar.

Passo 4: Verificar a Configuração

1. Crie uma postagem de teste com uma URL de PR do GitHub
2. Verifique se o onebox é exibido com um ícone de status
3. Altere o status do PR no GitHub (por exemplo, aprove-o ou feche-o)
4. Após alguns segundos, atualize a página do Discourse — o status deve ser atualizado

Você pode verificar o status de entrega do webhook nas configurações do webhook do GitHub para confirmar que os eventos estão sendo enviados e recebidos com sucesso.

Prioridade de Status

Quando um PR tem vários estados (por exemplo, aprovado mas também tem alterações solicitadas), o status é determinado pela seguinte prioridade:

1. Mesclado (maior prioridade)
2. Fechado
3. Rascunho
4. Alterações Solicitadas
5. Aprovado
6. Aberto (padrão)

Lógica de Status de Revisão

O recurso busca informações de revisão da API do GitHub para determinar o status de aprovação:

• Pega a última revisão de cada revisor
• Ignora os estados de revisão “comentado” e “pendente”
• Exibe “alterações solicitadas” se algum revisor tiver solicitado alterações
• Exibe “aprovado” apenas se existirem revisões e nenhuma solicitar alterações

Onde Funciona

• Postagens do fórum — Qualquer postagem contendo um onebox de PR do GitHub
• Mensagens de chat — Oneboxes de PRs no chat também exibem status ao vivo

Nota: Oneboxes inline (quando um link aparece inline no texto em vez de como uma prévia completa) não exibem ícones de status.

Migrando do Componente de Tema GitHub Status

Este recurso substitui o componente de tema GitHub Status Indicators. Os dois não são compatíveis e não devem ser usados juntos.

Se você estiver usando o componente de tema atualmente:

1. Desative e remova o componente de tema github-status-theme
2. Ative este recurso embutido por meio da configuração github pr status enabled

---

Configuração

Token de Acesso do GitHub

Para que o recurso de linkback funcione e as insígnias sejam concedidas aos seus usuários, você precisa fornecer um token de acesso do GitHub. Você pode gerar seu token aqui: Sign in to GitHub · GitHub.

O recurso de linkback requer o escopo public_repo, e a concessão de insígnias não requer nenhum escopo (deixe tudo desmarcado se você quiser apenas insígnias). Como o escopo public_repo concede acesso de gravação aos repositórios, recomendamos criar uma conta descartável do GitHub que não tenha acesso a nenhum repositório e usá-la apenas para gerar um token.

Escopos de Token por Recurso

Recurso	Escopo Necessário
Insígnias	Nenhum escopo necessário
Linkback	public_repo
Status de PR (repositórios públicos)	Nenhum escopo necessário
Status de PR (repositórios privados)	repo

---

Referência de Configurações do Site

Configuração	Padrão	Descrição
enable discourse github plugin	false	Interruptor mestre para o plugin
github badges enabled	false	Ativar insígnias de contribuição do GitHub
github badges repos	(vazio)	URLs de repositórios para rastrear insígnias
github linkback enabled	false	Ativar linkbacks do GitHub para o Discourse
github linkback access token	(vazio)	Token de acesso para o recurso de linkback
github linkback projects	(vazio)	Projetos para criar linkbacks
github permalinks enabled	false	Substituir links do GitHub por permalinks
github pr status enabled	false	Ativar ícones de status de PR nos oneboxes
github webhook secret	(vazio)	Segredo para verificação de assinatura de webhook
github onebox access tokens	(vazio)	Tokens de acesso para a API do GitHub (formato: org|token)

---

Detalhes Técnicos

Uso da API de Status de PR

Quando um onebox de PR do GitHub é gerado, o Discourse faz até duas chamadas de API:

1. Dados do PR: GET /repos/{owner}/{repo}/pulls/{number} — Busca informações básicas do PR, incluindo estado, status de mesclagem e status de rascunho
2. Revisões: GET /repos/{owner}/{repo}/pulls/{number}/reviews — Busca dados de revisão para determinar o status de aprovação

Essas chamadas usam seu token de acesso configurado, se disponível, permitindo acesso a repositórios privados.

Segurança do Webhook

As solicitações de webhook são verificadas usando validação de assinatura HMAC-SHA256. O GitHub assina o payload do webhook com o seu segredo, e o Discourse verifica essa assinatura antes de processar. Assinaturas inválidas são rejeitadas com uma resposta 403.

Eventos de Webhook que Disparam Atualizações

• Alterações de estado do PR (aberto, fechado, reaberto)
• PR mesclado
• Alterações de status de rascunho (convertido para rascunho, pronto para revisão)
• Revisões de pull request enviadas
• Revisões editadas ou descartadas

Considerações de Desempenho

• O rebaking é enfileirado como um job de segundo plano de baixa prioridade para evitar impactar o desempenho do site
• Apenas postagens/mensagens com oneboxes completos de PRs do GitHub são rebaked (oneboxes inline são ignorados)
• O rebaking de mensagens de chat ignora notificações para evitar alertas duplicados

---

CHANGELOG

2025-12-10

• CORREÇÃO: Ignorar notificações ao rebaker mensagens de chat de webhooks do GitHub

2025-12-09

• CORREÇÃO: Ignorar rebaking de postagens com oneboxes inline de PRs do GitHub
• CORREÇÃO: Evitar estado intermediário ao rebaker postagens com oneboxes
• CORREÇÃO: Rebakar mensagens de chat quando o status do PR do GitHub for alterado
• UX: Usar min-height para evitar mudança de layout quando o ícone de status for alterado
• UX: Reduzir o tamanho do ícone de status do PR do GitHub no mobile

2025-12-08

• RECURSO: Adicionar status “alterações solicitadas” aos oneboxes de PRs do GitHub

2025-12-04

• RECURSO: Ícone de status ao vivo do PR do GitHub

2025-11-10

• RECURSO: Permitir e negar lista para linkbacks

2025-11-08

• RECURSO: Adicionar lista de ignorância de categoria para linkbacks do GitHub

2024-12-20

• DEV: Mover discourse-github para o núcleo (já não requer instalação separada)

[ImmaZoni (Justin)]

Qual é o processo para vários links? eles apenas os adicionam ao mesmo comentário de commit? ou criam um novo comentário toda vez?

[satonotdead]

Gostaria de saber se os badges de commits e PRs poderiam ser simplificados, pois estamos tentando evitar O paradoxo da escolha :)\n\nAtualmente, eu apenas fiz um fork e deletei os badges de commit, mas é claro que me perdi do badge de commit (porque estou commitando diretamente) e o fork não é igual a manter sempre o core.

[xomiamoore (Mia)]

@Discourse

• username/repository para repositórios específicos
• username/* para todos os repositórios de um determinado usuário

O curinga * não funcionou para mim em uma organização do GitHub, acabei colocando cada repositório individualmente. Mais alguém teve problemas com isso em uma organização em vez de um usuário?

[greyli]

Como definir o idioma do comentário de linkback?

[cultiv (Sebastiaan Janssen)]

Obrigado, eu realmente gosto deste plugin! Fiquei confuso sobre o sistema de emblemas e fiquei feliz em encontrar a explicação em um tópico diferente: Github Badges are not working. Its hard to see if I do something wrong or if the plugin is not working - #4 by simon

No entanto, essa resposta observa que

O plugin cria 6 emblemas:

Eu não vejo nenhum desses emblemas, não tenho certeza do que aconteceu? Existe uma maneira de (re)ativar a criação desses emblemas?

[cultiv (Sebastiaan Janssen)]

Para responder à minha própria pergunta, após algumas horas a tarefa agendada foi executada e foi quando os emblemas foram criados.

@cultiv

Existe uma maneira de (re)ativar a criação desses emblemas?

A maneira manual de fazer isso seria acionar o job do sidekiq, aparentemente.

[tomtjes (Thomas Reintjes)]

Requisição de recurso: excluir categorias e/ou tags do linkback

Temos uma categoria Anúncios na qual o plugin RSS automaticamente puxa novos lançamentos do GitHub. Quando as notas do lançamento incluem links para problemas, esses links também aparecem no Discourse e um linkback é criado, mas que não é útil para ninguém, criando desordem no GitHub.

Gostaria de poder excluir certas postagens, ou seja, categorias ou tags ou até mesmo apenas postagens do usuário que está configurado no plugin RSS, de criar linkbacks.

[david (David Taylor)]

Este plugin agora está incluído no core do Discourse como parte de Bundling more popular plugins with Discourse core. Se você auto-hospeda e usa o plugin, precisa removê-lo do seu app.yml antes da sua próxima atualização.