Créer parfaitement un bot Slack pour invoquer les actions GitHub via Hubot

Tutoriels

Si vous utilisez GitHub Actions comme votre pipeline de construction et de déploiement, et que votre équipe utilise également Slack, saviez-vous que vous n’avez même pas besoin de quitter Slack ? Créez un bot Slack pour invoquer les workflows GitHub Actions directement depuis Slack automatiquement !

Dans ce tutoriel, vous allez apprendre comment configurer un nouveau chatbot Slack en utilisant l’outil de construction de bot appelé Hubot et démarrer automatiquement un workflow GitHub Actions pour déployer du code sur un serveur.

Allons-y !

Prérequis

Ce tutoriel sera une démonstration pratique. Si vous souhaitez suivre, assurez-vous d’avoir les éléments suivants :

  • A Slack Workspace
  • A GitHub account and a GitHub personal token
  • A Linux server to deploy code to – This tutorial will use Ubuntu 19.
  • A local Linux machine – This tutorial will use Ubuntu so that all local commands will be Linux. If you’re running another operating system, the commands may be slightly different.
  • Des identifiants SSH pour vous connecter au serveur sur lequel vous allez déployer du code.
  • A code editor of your choice that understands YAML like Visual Studio Code.

Connexe : Automatisation des actions Git côté client avec Git Hooks

Création d’un projet et d’un flux de travail GitHub Actions

Avant de pouvoir invoquer rapidement les workflows GitHub Actions depuis Slack, vous devez d’abord créer le workflow.

Pour créer le workflow, créons un dossier de projet pour contenir tous les fichiers avec lesquels vous allez travailler.

Connexe :Comment mettre en place Visual Studio Code avec GitHub !

1. Ouvrez votre application de terminal préférée.

2. Exécutez maintenant la série de commandes ci-dessous pour créer le dossier de projet nommé Hubot et naviguez dedans. 

mkdir ~/Hubot # Créez un répertoire nommé Hubot
cd ~/Hubot    # Changez de répertoire vers Hubot

3. Ensuite, exécutez npm init pour créer un fichier package.json Node.JS. L’exécution de npm init crée un projet Node.JS standard qui inclut le fichier package.json contenant diverses informations sur le projet et tout paquets NPM dépendants. 

npm init      # Initialise le fichier package.json

4. Maintenant, créez un répertoire workflows et le fichier workflow deploy.yml. Le fichier de flux de travail est une série d’étapes définies dans une séquence que les actions GitHub suivront.

mkdir .github/workflows && touch deploy.yml

5. Ensuite, définissez chacun des secrets GitHub que votre workflow lira. Le workflow que vous êtes sur le point de créer fera référence à ces secrets. Étant donné que vous aurez besoin de l’adresse de votre serveur, du nom d’utilisateur, du mot de passe et du port de votre serveur pour SSH, créons des secrets GitHub.

Rendez-vous sur cette URL https://github.com/votreutilisateur/votrerepository/settings/secrets/actions où vous ajouterez vos secrets GitHub. Remplacez votreutilisateur par votre nom d’utilisateur GitHub et votrerepository par votre dépôt GitHub.

Cliquez sur le bouton Nouveau secret de dépôt, comme indiqué ci-dessous, pour remplir les informations sur le secret que vous ajoutez.

Adding GitHub Secrets

6. Maintenant, remplissez les champs Nom et Valeur du secret, puis cliquez sur Ajouter un secret pour l’enregistrer. La page sera redirigée vers la page des secrets GitHub où vous verrez tous vos secrets. Pour ajouter d’autres secrets, cliquez sur le bouton Nouveau secret de dépôt comme vous l’avez fait précédemment.

Assurez-vous de sauvegarder les secrets pour les variables données avec le même nom exact que vous référencerez les mêmes variables, qui sont HOST, USERNAME, PASSWORD et PORT.

Filling up Information for a GitHub Secret
Viewing All GitHub Secrets

7. Enfin, ouvrez le fichier de workflow ~/Hubot/.github/workflows/deploy.yml dans votre éditeur de code, et copiez/collez le code suivant. Le code ci-dessous est le workflow qui s’exécutera chaque fois que vous déclencherez le workflow via Slack ultérieurement.

Lorsque vous invoquez le workflow, plusieurs actions auront lieu :

  • Les actions GitHub vont analyser le fichier de workflow ci-dessous pour se connecter en SSH au host cible défini dans le secret HOST avec les secrets USERNAME et PASSWORD.
  • Ensuite, le workflow téléchargera le contenu du référentiel GitHub pour une branche spécifique ($branchName) en exécutant git pull origin$branchName. Assurez-vous que le nom de la branche contient le code que vous souhaitez déployer.
  • Vous utiliserez un Package de workflow provenant du GitHub Marketplace appelé ssh-remote-commands. Ce package a une belle enveloppe pour contourner le besoin de fournir uniquement l’hôte, le nom d’utilisateur, le mot de passe, le port et la commande à exécuter en production.

Assurez-vous que votre serveur a git installé avec les identifiants de connexion nécessaires pour extraire le code du référentiel GitHub

# Le nom qui sera référencé sera beaucoup plus utilisé de manière programmable 
name: deploy 
on:
  # L'événement respository_dispatch signifie à chaque déclenchement de l'API, 
  # ce fichier entier est exécuté
  repository_dispatch: 
    types: [deploy-service]
# Il peut y avoir plusieurs tâches, mais actuellement, 
# ce tutoriel ne fonctionnera que sur une seule
jobs:
  deploy:
    name: Deploy
    # Le nom de l'image de base où tous les codes YAML sont exécutés
    runs-on: ubuntu-latest
    steps:
    - name: executing remote ssh commands using password
      # appleboy/ssh-action@master est un package open-source 
      # qui se connecte à un serveur via ssh et exécute le script
      uses: appleboy/ssh-action@master
      # Ce sont généralement les variables dont le package a besoin 
      # pour se connecter au serveur et exécuter le script
      with:
       # Les secrets sont les variables de 
       # https://docs.github.com/en/actions/security-guides/encrypted-secrets

       # Votre hôte du serveur stocké sur les secrets github avec le même nom HOST
        host: ${{ secrets.HOST }} 
        # Le nom d'utilisateur de votre serveur pour vous connecter 
        # qui est stocké sur les secrets github avec le nom USERNAME
        username: ${{ secrets.USERNAME }} 
        # Le mot de passe de votre serveur pour vous connecter 
        # qui est stocké sur les secrets github avec le nom PASSWORD 
        password: ${{ secrets.PASSWORD }} 
        # Le port de connexion à votre serveur 
        # qui est stocké sur les secrets github avec le nom PORT
        port: ${{ secrets.PORT }}  
        # deploy-app.sh peut être n'importe quoi comme tirer du code depuis GitHub 
        # et redémarrer votre serveur web ou les files d'attente, etc. 
        # Assurez-vous d'avoir cloné le dépôt sur votre serveur 
        # Vous pouvez exécuter autant de scripts que vous le souhaitez 
        script: git pull origin {{ github.event.client_payload.branch

Exécution du flux de travail manuellement

Vous avez maintenant créé le flux de travail GitHub Actions à invoquer via Slack. Mais à ce stade, votre code est uniquement sur votre machine locale. Pour déclencher le flux de travail, vous devrez pousser le code vers GitHub.

Exécuter la série de commandes ci-dessous indique à git où le code doit être poussé et tiré, dans cet exemple, à partir de votre dépôt GitHub distant. Dans la commande git remote add origin ci-dessous, remplacez yourusername et yourrepository par votre nom d’utilisateur GitHub et votre dépôt

# Ouvrez github.com et créez un dépôt
git init # Initialise git
git remote add origin https://github.com/yourusername/yourrepository.git
git add . # Ajoute les nouveaux fichiers créés pour que git les suive
git commit -m "Created GitHub workflow file"
git push -u origin master

Testons d’abord si votre code fonctionne. Invoquez votre code manuellement en utilisant l’utilitaire curl populaire.

Exécutez la commande ci-dessous pour effectuer une requête POST vers votre dépôt GitHub https://github.com/username/repository/dispatches URL pour indiquer à GitHub de déclencher un fichier de flux de travail deploy.yml que vous avez créé précédemment. Remplacez username par votre nom d’utilisateur GitHub réel et repository par votre dépôt GitHub.

Remplacez $github_personal_token dans le code ci-dessous par votre jeton personnel.

# Effectue une requête POST à l'URL https://github.com/nom_utilisateur/dépôt/dispatches 
curl-X POST  https://github.com/username/repository/dispatches \
# Ajoute un en-tête pour accepter le type de contenu
-H 'Accept: application/vnd.github.everest-preview+json' \
# Ajoute un en-tête pour l'autorisation
-H "Authorization: token $github_personal_token" \
# Ajoute un contenu JSON dans le corps de la requête POST afin que vous puissiez envoyer plusieurs paramètres 
# à partir de cette section de données et vous pouvez effectuer diverses actions en fonction des arguments
--data '{"event_type": "deploy-service", "client_payload": {"environment": "'"$1"'", "ref": "'"$2"'"}}' # Vous pouvez transmettre le nom de l'environnement et la référence en tant que nom de branche afin de savoir sur quelle branche déployer sur quel serveur

Créez un bot Slack avec Hubot

Étant donné que vous avez pu déclencher manuellement le flux de travail des actions GitHub, c’est un bon début. Maintenant, essayons d’automatiser les mêmes étapes manuelles via un bot Slack. Vous allez créer un bot Slack, qui écoute vos commandes et déclenche l’action GitHub avec des arguments.

Vous avez deux options pour créer un bot Slack, soit à partir de zéro, soit à partir d’un package Hubot pré-construit pour les espaces de travail Slack. Dans ce tutoriel, vous utiliserez un package de bot pré-construit appelé Hubot. Hubot est un outil d’automatisation open source qui s’intègre à des services de chat comme Slack, Discord, Gitter, TeamSpeak, etc.

Créer un bot personnalisé sans utiliser une application comme Hubot prend beaucoup de temps. Pourquoi ? Parce que vous devrez gérer l’ensemble des processus d’installation, d’écoute des webhooks et d’hébergement du bot. Dans ce tutoriel, nous utiliserons l’application Hubot pour Slack afin de simplifier tous ces processus.

Installation de Hubot avec Npm

Étant donné que vous utilisez Hubot pour créer un bot Slack, commençons par télécharger et installer Hubot sur votre machine locale. Hubot sera le connecteur qui relie Slack et les actions GitHub.

1. Dans votre terminal, naviguez (cd) vers votre répertoire de projet (~/Hubot). 

cd ~/Hubot

2. Installez le package yo et generator-hubot globalement (-g) sur votre machine locale avec la commande npm install ci-dessous. Le package yo vous aide à installer de nouveaux projets en générant des projets dans n’importe quel langage (Web, Java, Python, C#, etc.). Le package generator-hubot utilise le package yo pour installer toutes les dépendances ainsi que les configurations initiales.

Une fois installé, vous pouvez exécuter la commande yo n’importe où car elle a été installée globalement.

npm install -g yo generator-hubot

3. Maintenant, créez une base Hubot boilerplate avec la commande suivante. Une boilerplate est une section de code incluse à de nombreux endroits. Sans une boilerplate, vous devez toujours écrire du code à partir de zéro.

La commande ci-dessous crée une base Hubot boilerplate dans votre répertoire de projet. La base Hubot lie Slack (--adapter=slack) afin que le robot puisse écouter et répondre aux messages à l’intérieur du canal Slack. yo hubot --adapter=slack

yo hubot --adapter=slack

Ajout de Hubot à votre espace de travail Slack

Maintenant que Hubot est installé sur votre machine locale, vous devez configurer Hubot pour communiquer avec Slack.

Installons Hubot dans votre espace de travail Slack.

1. Ouvrez votre navigateur Web et accédez aux paramètres d’administration de votre Slack avec l’URL, comme https://workspacename.slack.com/admin/settings. Remplacez workspacename par le nom réel de votre espace de travail Slack.

Cliquez sur Configurer les applications dans le panneau de gauche, comme indiqué ci-dessous, afin de pouvoir rechercher Hubot sur le marché. Slack dispose d’un marché où vous pouvez trouver des applications pré-construites.

Accessing Slack Admin Settings

2. Cliquez sur la barre de recherche, puis saisissez hubot pour rechercher Hubot dans le marché et sélectionnez Hubot.

Maintenant, cliquez sur le bouton Ajouter à Slack, comme vous le voyez ci-dessous, pour ajouter Hubot à votre espace de travail Slack.

Searching Hubot and Adding it to Slack Workspace

3. Enfin, remplissez quelques informations générales sur votre Bot, telles que le nom (deployerhubot) et l’icône. Notez le Token API car vous l’utiliserez plus tard dans Hubot Deployer pour activer le Bot à partir de votre projet Hubot que vous avez créé précédemment.

Setting up Bot Information and Taking Note of the API Token

Test de l’intégration du flux de travail des actions GitHub avec Slack

Vous avez maintenant Hubot installé sur votre espace de travail Slack, donc testons le bot en écoutant et en envoyant des messages dans le canal. Mais d’abord, vous devez activer le Bot.

1. Exécutez la commande ci-dessous à l’intérieur du répertoire racine du projet pour activer le Bot pour Slack (--adapter slack) à partir de votre dépôt Hubot (./bin/hubot). Assurez-vous de remplacer le $token par le jeton API que vous avez noté précédemment

HUBOT_SLACK_TOKEN=$token ./bin/hubot --adapter slack

2. Exécutez la commande ci-dessous pour inviter (/invite) le Bot (nomdubot) dans votre canal Slack. Remplacez nomdubot par le nom du Bot que vous avez enregistré à l’étape trois de la section « Ajout de Hubot à votre espace de travail Slack ». 

/invite deployerhubot

Maintenant, mentionnez un Bot avec un texte dans Slack, comme @deployerhubot ping, pour tester si l’intégration fonctionne. Si le Bot répond PONG, comme indiqué ci-dessous, alors tout est prêt.

Testing Hubot and Slack Integration

Si le Bot ne répond pas, accédez à votre dépôt GitHub dans votre navigateur Web et cliquez sur l’onglet Actions. Vous pouvez identifier le flux de travail qui a échoué car il a un badge de vérification rouge rond. Cliquez sur le flux de travail en échec pour voir ce qui a causé l’échec et corrigez-le.

Viewing Failed Workflows

Ci-dessous, vous pouvez voir que l’échec se situe sur l’exécution de commandes SSH distantes en utilisant un mot de passe. Après avoir corrigé le flux de travail, revenez à l’étape 3 et voyez si le Bot répond PONG.

Navigating to GitHub repository to fix failed workflow

Lancement d’un flux de travail GitHub Actions depuis Slack

Maintenant que vous avez activé votre Bot Slack, il est temps de lancer un flux de travail GitHub Actions depuis Slack !

Vous avez besoin de la flexibilité pour déployer la branche donnée vers un serveur donné, comme extraire les codes de la branche donnée. Vous allez apprendre au Bot à répondre automatiquement lorsque quelqu’un tape ***@*bot deploy API feature-x to production sur un canal Slack. Vous pouvez valider le nom de l’environnement où plus tard les gens ne pourront déployer que certains environnements et branches.

Pour automatiser les réponses du Bot :

1. Créez un répertoire nommé ~/Hubot/scripts. Le répertoire ~/Hubot/scripts est l’endroit où vous enregistrerez un script qui déclenche votre flux de travail GitHub.

2. Dans votre éditeur de code, créez un fichier nommé bot.js à l’intérieur du répertoire ~/Hubot/scripts. Copiez maintenant le code ci-dessous et collez-le à l’intérieur du fichier bot.js.

Le code ci-dessous permet au Bot d’écouter les messages de discussion sur le canal Slack, puis déclenche le flux de travail pour envoyer une réponse au canal Slack.

const validServices = ['api','app'];
const validEnvironments = ['production'];
robot.hear (`@${process.env.BOT_ID}`,async (bot) => {
    // Le bot s'intéresse uniquement à écouter le message 
    // comme @deploy api featurex vers la production 
    // Configuration de variables réutilisables
	  const payload = bot.message.text.split(" ")
    const service = payload[2];
    const branch = payload[3];
    const environment = payload[5];
    const username = bot.message.user.name;
    // Informer l'utilisateur que nous traitons la demande
    bot.send(`Roger that! Please wait.`);
// Valider si la commande utilisée est valide ou non 
// car l'utilisateur peut également utiliser des commandes invalides 
if(!validateCommand(bot,username,service,branch,environment)) {
      return;
    }
    // Si la commande semble valide, déclencher un flux de travail
    await triggerWorkflow(bot,username,service,environment,branch)
    
    // Informer l'utilisateur que le flux de travail a été déclenché avec succès
    bot.send(`Github Action has been triggered successfully`);
  })
  const validateCommand = (bot,username,service,branch,environment) => {
    // Limiter les services car les utilisateurs peuvent utiliser des services qui ne sont pas répertoriés 
    // ce qui tentera de déclencher le flux de travail et génère une erreur
    if(!validServices.includes(service)) {
       bot.send(`${service} is not availble, Only ${validServices.join(', ')} are available`);
      return false;
      }
      // Limiter l'environnement car les utilisateurs peuvent utiliser une liste d'environnements invalide 
      if(!validEnvironments.includes(environment)) {
        bot.send(`${environment} is not availble. Only ${validEnvironments.join(', ')} are available`);
        return false;
      }
      return true;
  }

  const triggerWorkflow = (bot,username,service,environment,branch) => {
    try {
      // Il s'agit du même code de déclenchement de flux de travail manuel converti 
      // de curl à une requête post javascript réelle
      const data = await axios.post(`https://api.github.com/repos/yourusername/yourreponame/dispatches`,{
        'event_type': 'deploy-service',
        'client_payload': {'environment': environment, 'ref': branch}
      },{headers:{
      Authorization: `token ${token}`,
      }})
    }
      catch(e) {
        bot.send(`Sorry @${username} could not trigger github action. Please check my logs ${e.message}`);
      }
  }

3. Enfin, envoyez le message @nomdubot deploy api staging to dev dans Slack, et vous verrez une réponse similaire, comme indiqué ci-dessous.

Les fichiers de workflow peuvent être déclenchés sur différents événements GitHub, comme pousser du code vers une certaine branche, créer des tags, créer des demandes de tirage, demander des URL, et bien plus encore.

send the @botusername deploy api staging to dev message in slack

Conclusion

Tout au long de ce tutoriel, vous avez appris sur le Workflow GitHub, depuis le déclenchement manuel des réponses Slack avec des codes jusqu’à la construction d’un chatbot. Vous avez également appris qu’avoir un chatbot dans Slack vous permet d’automatiser des tâches en invoquant le workflow des actions GitHub.

Allez-vous pousser cette nouvelle connaissance à un niveau supérieur, peut-être en ajoutant un Bot de rappel ou en créant des messages interactifs?

Source:
https://adamtheautomator.com/create-slack-bot/