A deploy hook is a secret URL that queues a new deployment when something sends it an HTTP POST. There is no authentication header: the secrecy of the URL is the authentication. Use hooks to let a…

Acionando Implementações Via Deploy Hooks

Um deploy hook é uma URL secreta que enfileira uma nova implementação quando algo envia um HTTP POST para ela. Não há cabeçalho de autenticação: o sigilo da URL é a autenticação. Use hooks para permitir que um CMS headless, uma tarefa cron, um pipeline de CI ou qualquer outro webhook reconstrua seu projeto sem um git push.

Onde Encontrar Deploy Hooks

Os hooks têm sua própria aba: abra seu projeto em Orbit e clique em Hooks, em /orbit/<project-id>/hooks.

O mesmo painel de Deploy hooks também aparece na metade inferior da aba Settings do projeto, para que você possa gerenciá-los de qualquer lugar.

Deploy hooks panel in Orbit

Criando um Deploy Hook

Abra Orbit, depois seu projeto, depois Hooks.
Clique em Add deploy hook.
Digite um Hook name que ainda faça sentido em seis meses. O espaço reservado sugere o padrão: "Contentful publish", "Nightly cron".
Escolha um Target environment. O padrão é Production (default). Se seu projeto tiver um ambiente de staging, você pode apontar o hook para staging em vez disso.
Clique em Create hook.

O hook aparece na lista com sua URL, um botão Copy URL e um botão Delete hook.

A URL do Hook

As URLs de hook parecem assim:

https://kpanel.kapsulehost.com/api/orbit/hooks/<token>

O token é um segredo único gerado quando você cria o hook.

Trate uma URL de hook exatamente como uma chave de API. Qualquer pessoa que a tiver pode acionar uma implementação de seu projeto, e nenhuma das portas de implementação da Orbit as impedirá: deploy locks, aprovação obrigatória, verificações de CI obrigatórias e sucesso de staging obrigatório aplicam-se apenas a implementações acionadas por push, e um hook passa direto. Nunca cole uma URL de hook em um repositório público, um documento compartilhado, uma captura de tela ou um ticket de suporte.

Acionando um Hook

Envie uma solicitação POST. Nenhum corpo e nenhum cabeçalho são necessários.

curl -X POST \
  https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>

Orbit responde com HTTP 202 e o ID da implementação. A implementação aparece na aba Deployments em alguns segundos.

O endpoint aceita apenas POST. Uma solicitação GET não acionará uma implementação. Algumas integrações de webhook mais antigas usam GET por padrão, então verifique o método se um hook que você configurou nunca é acionado.

O Que um Hook Realmente Implementa

O hook resolve seu ambiente de destino (o que você escolheu, ou o ambiente de produção do projeto), lê o branch desse ambiente e solicita ao seu provedor de git o commit de head atual desse branch. Ele então enfileira uma implementação desse commit.

Isso tem três consequências que valem a pena saber:

Um hook sempre implementa o head do branch. Você não pode passar um SHA de commit ou um nome de branch no corpo da solicitação; o corpo da solicitação é completamente ignorado.
Um hook precisa de uma conexão de provedor funcionando. Se você desconectou GitHub, GitLab ou Bitbucket, o hook não consegue ler o head do branch e falha com um erro em vez de implementar código obsoleto.
Um hook executa novamente a compilação completa. Não é um rollback e não é uma promoção; é uma compilação nova do que quer que esteja no branch no momento.

Chamadas Repetidas e Sobrepostas

Orbit lida com rajadas de chamadas de hook de forma sensata, em vez de enfileirar uma compilação para cada uma.

Se uma implementação para o mesmo commit já estiver em andamento nesse ambiente, o hook retorna a implementação existente e marca a resposta como desduplicada. Nenhuma segunda compilação é iniciada.
Se uma compilação estiver em execução para um commit diferente nesse ambiente, ela é cancelada automaticamente e substituída pela nova, para que você não pague por uma compilação cuja saída já foi superada.

Isso torna os hooks seguros para um CMS que dispara um webhook por entrada publicada. Publicar seis páginas em um minuto produz uma compilação, não seis, e não consome os minutos de seis compilações.

Conectando um CMS Headless

A maioria dos CMSes headless tem um recurso "webhook on publish". O padrão é sempre o mesmo: aponte o webhook para sua URL de hook, use POST e deixe as configurações de autenticação vazias.

Contentful

Vá para Settings, depois Webhooks, depois Add webhook.
Defina a URL para sua URL de hook do Orbit.
Defina o método para POST.
Defina o gatilho para Publish, ou quaisquer eventos de conteúdo que devem reconstruir o site.
Salve.

Sanity

No painel do seu projeto, vá para API, depois Webhooks, depois Create webhook. Defina a URL para sua URL de hook, o método para POST e escolha o dataset e os eventos de gatilho.

Prismic

No painel, vá para Settings, depois Webhooks, e adicione sua URL de hook. Prismic a chama em cada publicação de documento.

Conectando uma Tarefa Cron ou Pipeline de CI

Qualquer agendador que possa fazer uma solicitação HTTP funcionará:

# crontab: rebuild every night at 2am
0 2 * * * curl -fsS -X POST https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>

Para CI, um deploy hook é a opção mais simples quando você quer que seu pipeline decida se uma implementação acontece. É a abordagem recomendada para Bitbucket Pipelines, pois a configuração de verificações de CI obrigatórias do Orbit faz gates em nomes de trabalho do GitHub Actions ou em um pipeline do GitLab, não no Bitbucket.

Se você precisar de mais do que "implementar o head do branch", use um token de API em vez de um hook. Orbit, depois Tokens, cria bearer tokens com escopo para CI/CD com uma API REST documentada e um fluxo de trabalho GitHub Actions pronto para usar. O acesso por API está incluído no plano Apex.

Reconstruindo em um Cronograma Sem um Hook

Se tudo o que você quer é uma reconstrução periódica, você não precisa de um hook. Scheduled rebuild em Settings, em Runtime, reconstrói a produção automaticamente a cada hora, 6 horas, 12 horas, diariamente, a cada 2 dias ou semanalmente. É construído exatamente para o caso de site orientado por CMS e não há URL secreta para proteger.

Verificando a Atividade do Hook

Cada linha de hook mostra quantas vezes foi usada e quando foi usada pela última vez, na forma "Used 14 times, last 3 Jul". Esta é a forma mais rápida de confirmar que seu CMS está realmente chamando o hook quando você acha que está.

Se a contagem não está aumentando, o problema está no lado chamador: verifique se o método é POST, a URL é exata e a integração não está falhando silenciosamente em um erro de TLS ou firewall.

Deletando um Hook

Clique em Delete hook na linha e confirme. O diálogo avisa que qualquer serviço que o usar deixará de funcionar, que é exatamente o que acontece.

Não há forma de rotacionar o token de um hook em seu lugar. Se uma URL vazar, você deleta o hook e cria um novo, depois atualiza cada sistema que usou a URL antiga. A exclusão entra em efeito imediatamente, então planeje a troca antes de deletar em vez de depois.

Solução de Problemas

Nada acontece quando chamo o hook. Verifique se o método é POST. Verifique a URL caractere por caractere, incluindo o token. Verifique a contagem de uso do hook na aba Hooks: se não está incrementando, a solicitação nunca chegou.

O hook retorna um erro sobre o commit mais recente. Orbit não conseguiu ler o head do branch do seu provedor de git. Reconecte o provedor de Orbit, depois New project, depois Reconnect, e confirme que o repositório ainda está acessível.

O hook retorna um erro sobre o ambiente de destino. O ambiente para o qual o hook apontava não existe mais, muito provavelmente porque um ambiente de staging foi deletado. Delete o hook e crie um novo contra um ambiente ativo.

O hook é acionado mas a implementação é a mesma de antes. Esse é o comportamento de desduplicação: o head do branch não mudou, então não há nada novo para compilar. Faça um push de um commit, ou use Deploy now se você especificamente quer reconstruir o mesmo commit.

Leitura Relacionada

Deploying Your Project para as portas de implementação e quais delas os hooks contornam
Connecting a Bitbucket Repo para o caso de gate de CI que os hooks resolvem
Environment Variables, pois uma compilação acionada por hook lê a mesma configuração que qualquer outra

Acionando Implantações Via Deploy Hooks