Gatilhos do Git

Um push na branch de um stack pode disparar o run sozinho. Os gatilhos vêm desligados, então nada muda até alguém ligar. Ligar também não dispara nada: vale a partir do próximo push.

Isso funciona hoje com o Gitea, para stacks criados pela conexão Git da organização. Um stack que clona com um token próprio não pode usar.

Quem dá push executa código. Com o gatilho ligado, quem escreve na branch roda código com as credenciais do stack já no plan, antes de qualquer aprovação. Use proteção de branch no Gitea.

Como configurar

Gerar o segredo e criar o webhook ainda são passos manuais. Instalar o webhook pela tela está planejado.

1. Gere o segredo do webhook

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://firstlume.example.com/api/v1/orgs/{org}/git/webhook-secret

A resposta traz o que o webhook precisa:

{
  "url": "https://firstlume.example.com/webhooks/v1/gitea/<connection-id>",
  "secret": "flw_...",
  "content_type": "json",
  "events": ["push", "pull_request", "pull_request_sync"]
}

• O segredo só aparece nesta resposta e serve para todos os repositórios da conexão.
• Chamar de novo troca o segredo. Webhooks que assinam com o antigo são recusados até você atualizá-los.
• A URL vem de FIRSTLUME_PUBLIC_URL (controlPlane.publicURL no Helm).
• Uma organização sem conexão Git recebe 404.

2. Crie o webhook no Gitea

Em cada repositório, crie um webhook do tipo gitea com essa URL e esse segredo, content_type json e os eventos push, pull_request e pull_request_sync. É preciso ser admin do repositório. Pela API do Gitea:

curl -X POST -H "Authorization: token $GITEA_TOKEN" -H "Content-Type: application/json" \
  https://gitea.example.com/api/v1/repos/{owner}/{repo}/hooks -d '{
    "type": "gitea",
    "active": true,
    "events": ["push", "pull_request", "pull_request_sync"],
    "config": {"url": "<url>", "secret": "<secret>", "content_type": "json"}
  }'

Hoje só o push dispara runs. Os eventos de pull request são aceitos e ignorados, até o plan em pull request existir.

O Gitea recusa endereços privados por padrão, e a entrega falha com webhook can only call allowed HTTP servers. Numa instalação interna, libere o host do First Lume no app.ini do Gitea e reinicie o Gitea:

[webhook]
ALLOWED_HOST_LIST = firstlume.example.com

3. Ligue o gatilho

Ajuste On push nas configurações da organização, de uma pasta ou do stack. Ele é herdado como as outras configurações. Na API, é o git_on_push:

curl -s -X PUT -H "$H" $O/folders/$F/settings -d '{"git_on_push": "plan"}'

Um PUT substitui o que o nível define. Envie junto as outras configurações e variáveis do nível.

Com apply e aprovação ligada, aprovar aplica exatamente o commit do push. Com a aprovação desligada, ninguém revisa o plano antes de ele mudar a infraestrutura. Um merge também é um push na branch, então conta. Um gatilho nunca cria um run destroy.

4. Confira

Dê um push e abra Git events. O push aparece lá, com a decisão de cada stack.

O que conta como afetado

Um stack é afetado quando muda algum arquivo dentro do path dele. Com o path na raiz, todo arquivo conta.

Módulos fora do path só contam se forem declarados em .firstlume/config.yaml, com caminhos relativos à raiz do repositório:

triggers:
  paths:              # afeta também quando estes mudam
    - modules/**
    - root.hcl
  ignore:             # não conta quando só estes mudaram
    - "**/*.md"

Um módulo não declarado não dispara run, e a mudança dele fica sem aplicar. Uma verificação de drift mostra a diferença.

Quando não há como saber o que mudou, todos os stacks da branch contam como afetados: force push, branch nova, ou uma comparação dos commits que falha ou volta incompleta. Um config.yaml inválido ou ilegível naquele commit também faz o stack dele contar, para o run falhar e mostrar o motivo. Rodar a mais termina em no_changes, e rodar a menos deixaria mudança sem aplicar.

Pushes em outras branches, tags e branches apagadas não disparam nada.

Um push novo substitui o que ficou velho

Um run fica preso ao commit do push, e cada push cria no máximo um run por stack, mesmo que o Gitea entregue duas vezes. Quando um push mais novo chega à branch:

• runs de pushes anteriores que estão na fila são cancelados
• runs de pushes anteriores que aguardam aprovação são descartados, com a mensagem superseded by <commit>
• um run que já está executando termina, e o novo espera na fila

Runs iniciados por uma pessoa nunca são tocados.

Por que não rodou?

A aba Runs do stack mostra quando o último push não disparou nada, e por quê. A página Git events, na seção Git connection das configurações da organização, mostra cada push recebido e a decisão para cada stack. Pela API:

curl -s -H "$H" "$O/git/events?stack=$ST"

Os eventos ficam guardados por 30 dias.

Se o On push está ligado e nenhum evento chega, as configurações e o stack avisam Nothing received. Confira, começando pelas entregas recentes do webhook no Gitea:

• o ALLOWED_HOST_LIST, como no passo 2
• se o segredo foi trocado depois de criar o webhook: uma assinatura errada recebe 401 e não deixa evento
• se o repositório é da conta da conexão: pushes de qualquer outro são ignorados e não deixam evento

O que o run mostra

Um run disparado por push diz quem deu o push, o commit e, quando o commit veio de um pull request, um link para ele. Veja em Runs e aprovação o resto do ciclo, que é igual ao de qualquer outro run.

Planejado

Isto ainda não existe:

• Plan em pull request, com comentário e status no Gitea
• Status de commit no Gitea para runs disparados por push
• Instalar o webhook pela tela
• Uma varredura a cada 5 minutos, para pegar pushes cujo webhook se perdeu
• GitHub e GitLab