O webhook do GitHub não chega ao Jenkins privado: corrija o caminho

Pode abrir o Jenkins pela VPN e ainda assim ver o GitHub a reportar um webhook falhado, porque são duas ligações diferentes com dois responsáveis diferentes. O navegador viaja num túnel negociado pelo portátil; o serviço de entrega do GitHub começa na internet pública e não tem rota para a rede privada. O acesso ao repositório não muda isso, embora o próprio Jenkins possa obter do mesmo repositório sem problemas. Escolha um ponto de entrada, um relay ou o polling, e depois teste o caminho que o evento realmente percorre.

Uma sessão de navegador prova apenas uma direção

Uma ligação VPN responde a uma pergunta: consegue este portátil chegar ao anfitrião interno. A entrega de webhooks pergunta outra: consegue um serviço externo abrir uma ligação a esse anfitrião. O facto de o Jenkins obter de um repositório é tráfego de saída e não diz nada sobre a acessibilidade de entrada. Mantenha as duas direções em linhas separadas no seu diagrama, incluindo que lado inicia cada uma.

Leia o registo de entrega antes de mudar seja o que for. Um tempo limite, um reinício de ligação e um pedido aceite que não correspondia a nenhuma tarefa têm três responsáveis diferentes: rede, proxy e configuração do gatilho.

Opção A: expor um ponto de entrada estreito

Se a organização já publica uma entrada aprovada, exponha o caminho do webhook em vez do painel. Normalmente isso significa uma regra de proxy inverso que aceita POST no URL do gancho e os reencaminha para o Jenkins, enquanto a interface de administração continua inacessível do exterior.

curl -sS -o /dev/null -w "%{http_code}\n" -X POST https://jenkins.example.com/github-webhook/

Execute esse teste a partir de uma rede sem acesso VPN, porque um sucesso de dentro do túnel não prova nada. O ponto de entrada deve rejeitar pedidos sem o segredo partilhado, que o GitHub envia como cabeçalho de assinatura, e aceitar apenas o único caminho e método que publicou. Uma consola do Jenkins pública não é uma correção do webhook; é um incidente à espera do próximo scanner. Restrinja a regra o suficiente para que o resto da aplicação mantenha os controlos de acesso que tinha.

Opção B: inverter a direção com um relay

Onde a exposição de entrada não for aprovada, um pequeno cliente dentro da rede pode manter uma ligação de saída para um relay e receber os eventos reencaminhados. O relay passa então a fazer parte do caminho de entrega, por isso a sua disponibilidade e autenticação importam tanto como a tarefa de compilação.

ssh -N -R 9000:localhost:8080 relay.example.net

As orientações do Jenkins sobre webhooks atrás de firewalls descrevem esta forma, e vale a pena lê-las antes de escrever o seu próprio reencaminhador. Termine o TLS no relay, verifique a assinatura antes de o evento chegar à tarefa e monitorize a ligação de saída, porque um túnel caído parece exatamente um evento que nunca foi enviado. Confirme também que o relay preserva o corpo do pedido byte a byte, já que as verificações de assinatura falham em JSON que foi analisado e recodificado pelo caminho.

Opção C: inquirir o repositório

O polling troca latência por simplicidade e não precisa de qualquer caminho de entrada. O Jenkins pode inquirir segundo um horário, ou uma pequena tarefa pode consultar a API e iniciar uma compilação quando vê uma revisão desconhecida.

curl -sS -u "$USER:$TOKEN" "https://api.github.com/repos/OWNER/REPO/commits?per_page=1"

Cada inquirição gasta chamadas à API e acrescenta um atraso entre o push e a compilação, o que se torna visível em repositórios movimentados e em limites de velocidade partilhados. Também precisa de credenciais guardadas onde quer que o inquiridor corra, por isso limite o token a acesso só de leitura ao repositório e rode-o como qualquer outro segredo. Escolha isto quando o volume de eventos for baixo ou quando nunca for aprovado um ponto de entrada, e diga-o na descrição da tarefa para que ninguém se pergunte mais tarde porque é que as compilações atrasam.

Aceite uma entrega real, não um carregamento de página

Seja qual for a opção escolhida, o teste de aceitação é um evento enviado pela plataforma de origem, não um separador do navegador aberto a partir de um portátil privilegiado. Faça push de um commit vazio para um ramo temporário e leia o código de resposta da entrega, o registo do relay ou a saída da tarefa de polling, nessa ordem. Um 200 do ponto de entrada sem compilação significa que o filtro do gatilho está errado; um tempo limite significa que o caminho continua fechado. Registre qual dos três desenhos está em uso, porque caso contrário a próxima pessoa a depurar repetirá o teste do navegador e chegará ao mesmo beco sem saída.

Aplique o mesmo raciocínio aos callbacks de pagamento e a outras notificações externas: cada uma precisa da sua própria rota para a aplicação privada, mesmo quando todas as pessoas já têm uma sessão VPN. O caminho de entrega pertence ao desenho da aplicação, não a uma nota de rodapé sobre redes.