Como integrar GitHub Actions com Slack, Telegram e WhatsApp
Que tal fazer a sua Integração Contínua mandar um “zap”?
A CI disponibilizada pelo GitHub, também chamada de GitHub Actions, disponibiliza algumas integrações com as plataformas de comunicação mais utiizadas no nosso dia a dia, como Slack, Telegram e Whatsapp. Assim, podemos informar nossas equipes automaticamente sobre etapas da nossa Integração Contínua, e é sobre isso que vamos conversar neste post.
Então vamos lá? Bora fazer a sua CI mandar um "zap"! 😃
Para que seja possível realizar a integração, é necessário entender alguns conceitos. O próximo tópico tem o objetivo de nivelar seu conhecimento sobre o conceito de segredos do repositório no GitHub.
Segredos do repositório
Para que seja possível integrar a CI com essas ferramentas de terceiros (Slack/Telegram/WhatsApp), é necessário que o GitHub Actions utilize credenciais privadas, e a forma segura de adicionar essas credenciais ao seu repositório é por meio dos segredos do repositório. Dessa forma, suas credenciais privadas não ficam disponíveis explicitamente no repositório, e são salvas de forma criptografada. Para localizar a lista de segredos do seu repositório siga as etapas:
- Acesse as configurações do repositório
2. Clique em Segredos e selecione Actions
Todos os segredos adicionados aqui serão criptografados 🔐 e apenas utilizados para o GitHub Actions. Esses segredos podem ser referenciados nas suas instruções .yml da seguinte forma:
${{ secrets.nome_do_seu_segredo }}Nesse caso, será retornado o conteúdo do segredo salvo com o nome "nome_do_seu_segredo" nos segredos do repositório.
Integrando com Slack
Vamos utilizar esse action para isso. Considerando que já temos um workspace criado no Slack e com um channel dedicado para a nossa CI, podemos integrar esse channel com o App do Slack WebHooks de entrada. Com esse App vamos obter um link que será usado no GitHub Actions para enviar mensagens no Slack. Para isso siga os passos abaixo para obter o link que será utilizado para enviar mensagens:
- Selecione o channel do slack
- Selecione a seta ao lado do nome do channel
- Clique em “Integrações”
- Pesquise e selecione “Incoming WebHooks”
- Selecione “Adicionar ao Slack”
- Selecione o channel desejado
Esses passos podem ser visualizados abaixo:
Ao final desse processo, vai aparecer a página "Instruções de instalação", contendo um link no seu primeiro tópico "URL do webhook". Copie esse link.
Crie um segredo do repositório contendo o link com o seguinte nome:
SLACK_WEBHOOK_URLComo mostram os passos abaixo:
Agora, podemos montar nosso arquivo .yml da seguinte forma:
(Crie o arquivo na raiz do repositório em “.github/workflows/notifier.yml”.)
Alguns pontos sobre esse código:
- Linha 17 = SLACK_CHANNEL = Aqui podemos adicionar o nome do canal
- Linha 18 = SLACK_TITLE = Aqui podemos adicionar o título da postagem
- Linha 19 = SLACK_USERNAME = Aqui podemos adicionar o nome do usuário que vai estar associado a mensagem
- Linha 21 = SLACK_MESSAGE = A mensagem em si.
- Linha 20 = SLACK_WEBHOOK = Propriedade armazenada com o segredo do repositório contendo o link para o webhook.
Ao executar a CI o resultado será o seguinte 😃
Integrando com Telegram
Para a integração com o Telegram, vamos usar uma telegram-action que interage com um bot. Para utilizar o bot, precisamos primeiramente criar o bot (com um token), e um chat.
Criando seu bot
Baseado na documentação do Telegram sobre bots, siga os seguintes passos:
- Acesse BotFather e clique em "Send message"
- No chat com BotFather envie a mensagem:
/newbot- Em seguida envie o nome do bot que deseja criar
- Envie o nome único de usuário (que será usado pelo seu bot) que será associado
- Ao criar o bot, será enviada uma mensagem de sucesso contendo um token
OBS.: O token gerado é no formato abaixo:
1234567890:ABCDE123ABCDE123ABCDE123ABCDE123ABCCriando chat
Agora que temos um bot, podemos criar um chat. Para isso, no App do Telegram seguir os passos abaixo:
- Pesquisar pelo nome único de usuário associado ao seu bot (passo 4 da criação do bot)
- Iniciar uma conversa com esse usuário
- Enviar a mensagem:
/start- Enviar uma mensagem qualquer
Obtendo id do chat (que iniciamos acima)
Finalmente temos um bot e um chat, agora precisamos do id do chat. Para obter o id do chat:
- Abra o terminal
- Execute o comando abaixo (adicionando o token no lugar do "TOKEN")
curl https://api.telegram.org/botTOKEN/getUpdates- Obter o id do chat dentro da resposta dessa API (id em negrito abaixo XXXXXXXXX)
{
"ok":true,
"result":[
{
"update_id":777368030,
"message":{
"message_id":1,
"from":{
"id":1234567890,
"is_bot":false,
"first_name":"YourUserName",
"username":"YourTelegramUser",
"language_code":"pt-br"
},
"chat":{
"id":XXXXXXXXX,
"first_name":"YourUserName",
"username":"YourTelegramUser",
"type":"private"
},
"date":1234567890,
"text":"/start",
"entities":[
{
"offset":0,
"length":6,
"type":"bot_command"
}
]
}
}
]
}Para mais detalhes sobre bots do Telegram, acesse Telegram Bots API.
Configurando Action
Ufa 😮💨 Agora que temos em mãos nosso token do bot e nosso id do chat, podemos colocar essas informações dentro do secrets do nosso repositório.
O token do bot será adicionado dentro do secret TELEGRAM_TOKEN e o id do chat dentro de TELEGRAM_TO. Ao adicionar os secrets, o painel de secrets do repositório vai ficar dessa forma:
Agora, podemos montar nosso arquivo .yml da seguinte forma:
(Crie o arquivo na raiz do repositório em “.github/workflows/notifier.yml”.)
Observe que o conteúdo da message (a partir da linha 19) pode ser customizado para seu contexto.
Ao executar a CI o resultado será o seguinte 😃
Integrando com WhatsApp
Utilizaremos esse action e uma ferramenta terceira para que seja possível enviar mensagens. O nome dessa ferramenta é Twilio. Vamos seguir os passos abaixo para realizar essa integração.
OBS.: existe um trial de $15 dólares ao criar sua conta. Importante observar que essa aplicação é paga no modelo pay-as-you-go. Veja mais detalhes em Twilio WhatsApp Pricing.
- Criar uma conta no Twilio
2. Configurar os segredos do repositório
3. Crie os segredos no seu repositório:
WPP_TWILIO_TO_WHATSAPP_NONesse segredo adicione o seu número de celular usado no WhatsApp com o código do país e cidade, no seguinte formato: 5511900001111
4. Para obter o seu account sid e auth token, acesse o console do Twillio:
5. Criar os seguintes segredos no repositório para adicionar seu account sid e auth token respectivamente:
WPP_TWILIO_ACCOUNT_SIDWPP_TWILIO_AUTH_TOKEN
Ao adicionar esses três segredos, sua lista vai parecer assim:
5. Envie uma mensagem para Twilio.
Utilizando o menu lateral esquerdo, acesse Messaging / Try it out / Send a WhatsApp message. Envie a mensagem indicada (no caso "join merely-potatoes") para o número de WhatsApp indicado no site, como mostra o print abaixo:
Importante observar que, configurando dessa forma, as mensagens serão enviadas utilizando o número de WhatsApp da própria Twilio. Existe a possibilidade de registro de um número próprio para envio de mensagens conforme mostra a orientação oficial do site.
6. Crie o arquivo .yml no seu repositório.
(Crie o arquivo na raiz do repositório em ".github/workflows/notifier.yml".)
Observe que o conteúdo da message (linha 21) pode ser customizado da forma necessária para seu contexto.
Ao executar a CI o resultado será o seguinte 😃
Conclusão
Temos várias opções para comunicar nossas equipes sobre nossas etapas da CI, especificando quais etapas passaram. Conhecendo as ferramentas disponíveis, podemos fazer melhores escolhas dependendo da nossa necessidade. Espero que aproveite essa integração nos teus projetos. 😃
Tem alguma dúvida ou algo pra contribuir? Aproveite os campos de comentários! E se você quiser fazer parte de um time que está sempre aprendendo junto, dá uma olhada nas nossas vagas aqui e se candidate. Até a próxima!
Referências
- GitHub Secrets Documentation
- Telegram Action
- Telegram Bot Documentation
- Telegram Bot API Documentation
- Slack Action
- Twilio
- WhatsApp Action
