Envoyer des notifications de pipeline CI GitLab avec Nexmo Messages

Je gère mon propre blog, Le développeur polyglottequi est publié dans le cadre d'une intégration continue et d'un déploiement continu. Essentiellement, la série d'événements suivante se produit à chaque fois qu'un git push est effectuée :

1. Le site statique est poussé sur GitLab

2. Le processus de construction du pipeline démarre

3. Le processus de déploiement du pipeline commence

4. Le site statique est publié et prêt à être consommé.

Dans plus de circonstances que je ne voudrais l'admettre, le processus échoue parce que soit ma construction a échoué, soit le déploiement a échoué. Le problème, c'est que je ne sais pas souvent que ces échecs se produisent, ce qui entraîne parfois de nombreux retours en arrière.

Nous allons voir comment améliorer le processus CI / CD en incluant des notifications SMS alimentées par Nexmo en cas d'échec.

Comprendre la configuration et le processus de GitLab CI

Si vous n'êtes pas familier avec GitLab, vous pouvez utiliser leurs services CI en incluant un fichier .gitlab-ci.yml à la racine de votre projet Git. Ce fichier peut ressembler à ceci :

image: "node:alpine"

stages:
  - build
  - deploy

build:
  stage: build
  script: 
    - npm install
    - npx gulp build
    artifacts:
      paths:
        - dist

deploy:
  stage: deploy
  script:
    - npm install
    - npx gulp deploy

La configuration ci-dessus est fictive, mais elle suit un formatage correct du fichier .gitlab-ci.yml correctement formaté. Dans le scénario ci-dessus, il y a une étape build qui exécute la tâche build gulp et une étape deploy qui exécute la tâche deploy gulp.

Si l'une des deux étapes échoue, que se passe-t-il ?

Avec GitLab CI, vous pouvez définir quand certaines étapes s'exécutent, ce qui signifie que vous pouvez concevoir une étape qui s'exécute en cas d'échec. En gardant cela à l'esprit, nous pourrions mettre à jour notre fichier .gitlab-ci.yml pour qu'il ressemble à ce qui suit :

image: "node:alpine"

stages:
  - build
  - deploy
  - failure

build:
  stage: build
  script: 
    - npm install
    - npx gulp build
    artifacts:
      paths:
        - dist

deploy:
  stage: deploy
  script:
    - npm install
    - npx gulp deploy

failure:
  stage: failure
  script:
    - echo "failure"
  when: on_failure

L'élément d'information important est le when propriété qui existe sur la failure scène.

Maintenant que nous savons comment créer une configuration CI GitLab, comment l'utiliser à notre avantage pour nous notifier chaque fois qu'il y a une défaillance dans le pipeline ?

C'est là que Nexmo et le service SMS sont précieux.

Utiliser l'API SMS de Nexmo

Lorsque notre pipeline tombe en panne, nous pouvons utiliser le service SMS de Nexmo pour nous envoyer un message texte qui peut contenir des informations sur le pipeline, des informations sur l'engagement, ou vraiment tout ce qui peut être utile pour nous ou pour l'équipe responsable du projet.

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Pour utiliser l'API SMS de Nexmo, vous avez besoin d'un Account. Dans le menu Paramètres de votre Account, notez la clé et le secret de l'API.

Settings

Les informations relatives à l'API seront nécessaires pour l'envoi automatique de SMS.

Si nous le voulions vraiment, et nous ne devrions pas le faire, nous pourrions créer une déclaration cURL et coder en dur toutes les informations relatives à notre API et à notre numéro de téléphone et les ajouter directement à la configuration de l'IC de GitLab. Nous pourrions le faire, mais nous ne devrions pas. Au lieu de cela, nous devrions créer des variables d'environnement de pipeline dans GitLab.

Dans le menu CI / CD -> Paramètres de votre projet GitLab, développez l'onglet Variables (Variables).

Gitlab env variables

C'est ici que vous voudrez ajouter vos informations sensibles afin qu'elles ne soient pas exposées à tous ceux qui travaillent sur votre projet. Ajoutez la clé et le secret de l'API ainsi que le numéro de téléphone de destination du SMS. Pour les protéger de la sortie du journal du pipeline, assurez-vous que ces variables sont masquéesafin qu'elles n'apparaissent pas.

Reprenons maintenant le fichier .gitlab-ci.yml pour en faciliter la compréhension. Pour le rendre plus facile à comprendre, nous allons le réduire un peu et le faire ressembler à ce qui suit :

image: "alpine:latest"

stages:
  - build
  - notify

build:
  stage: build
  script: 
    - exit 1

notify:
  stage: notify
  script:
    - apk add curl
    - curl -X "POST" "https://rest.nexmo.com/sms/json" -d "from=15404161937" -d "text=${CI_PROJECT_NAME} ${CI_COMMIT_SHORT_SHA} Failed!" -d "to=${to}" -d "api_key=${api_key}" -d "api_secret=${api_secret}"
  when: on_failure

Remarquez que nous n'avons que deux étapes, dont l'une ne se produit qu'en cas d'échec. Dans l'étape build nous provoquons une défaillance à titre d'exemple. Cet échec déclenche l'étape notify où l'application cURL est téléchargée et une requête HTTP est faite à l'API SMS Nexmo.

Dans la requête cURL, certaines variables sont utilisées. Les variables ${CI_PROJECT_NAME} et ${CI_COMMIT_SHORT_SHA} sont des variables prédéfinies par GitLabmais les variables ${to}, ${api_key}, et ${api_secret} sont celles que nous avons définies et qui contiennent nos informations Nexmo.

Si vous poussez votre projet Git, il devrait envoyer un SMS en cas d'échec et ce SMS devrait inclure le projet qui a échoué ainsi que le commit qui a échoué.

Élargir les options de messagerie avec l'API Nexmo Messages

L'API SMS de Nexmo est excellente, mais qu'en est-il si vous souhaitez atteindre d'autres plateformes au-delà du simple SMS ? C'est là qu'intervient l'API Messages de Nexmo, qui offre une prise en charge des SMS, de Facebook Messenger, de Viber et de WhatsApp.

L'installation est un peu plus complexe, mais vous bénéficiez d'un plus grand nombre de fonctionnalités.

Pour commencer, vous aurez besoin d'une sorte de service d'arrière-plan. Comme Nexmo prend en charge Node.js, il est logique d'utiliser Node.js et JavaScript pour éviter d'avoir à fabriquer vos propres requêtes HTTP.

Créez un nouveau répertoire de projet, qui sera hébergé en dehors de votre projet GitLab. Dans ce répertoire, exécutez ce qui suit :

npm init -y
npm install nexmo@beta express --save
touch main.js

Les commandes ci-dessus créeront un nouveau fichier package.json un fichier main.js pour toute la logique de l'application, et installer chacune des dépendances.

Le but de ce backend est de contrôler les webhooks que le service Nexmo utilisera. Lorsque vous travaillez avec l'API Messages de Nexmo, un élément de type statut et un webhook inbound sont nécessaires dans le cadre du flux de messages.

Ouvrez le fichier main.js et incluez ce qui suit :

const Express = require("express");
const Nexmo = require('nexmo');

const server = Express();

server.use(Express.json());
server.use(Express.urlencoded({ extended: false }));

const nexmo = new Nexmo({
    apiKey: "NEXMO_API_KEY",
    apiSecret: "NEXMO_API_SECRET",
    applicationId: "NEXMO_APPLICATION_ID",
    privateKey: "NEXMO_PATH_TO_PRIVATE_KEY"
});

server.post("/status", (request, response, next) => {
    console.log(request.body);
    response.send(request.body);
});

server.post("/inbound", (request, response, next) => {
    console.log(request.body);
    response.send(request.body);
});

server.listen("3000", () => {
    console.log("Listening at :3000...");
});

Pour l'instant, ignorez les jetons. Nous nous occuperons de les obtenir dans un instant.

Le code ci-dessus crée un simple serveur Node.js avec deux points d'extrémité d'API qui représenteront les webhooks nécessaires. Dans notre scénario, nous allons seulement imprimer les requêtes qui arrivent dans les webhooks et les renvoyer au demandeur.

Une demande entrant dans le statut pourrait ressembler à ceci :

{
    message_uuid: 'UUID_STRING',
    to: { number: 'RECIPIENT_PHONE_NUMBER', type: 'sms' },
    from: { number: 'SENDER_PHONE_NUMBER', type: 'sms' },
    timestamp: '2019-09-09T23:18:25.308Z',
    usage: { price: '0.0062', currency: 'EUR' },
    status: 'delivered'
}

Comme nous ne recevrons pas de messages de la part des utilisateurs, l'option inbound n'est pas très pertinent pour nous, même s'il est nécessaire.

Revenons donc à l'information sur les jetons :

const nexmo = new Nexmo({
    apiKey: "NEXMO_API_KEY",
    apiSecret: "NEXMO_API_SECRET",
    applicationId: "NEXMO_APPLICATION_ID",
    privateKey: "NEXMO_PATH_TO_PRIVATE_KEY"
});

Dès à présent, vous devriez déjà disposer de l'option apiKey et apiSecret de l'exemple précédent où l'API SMS a été utilisée directement avec cURL en cas d'échec du déploiement. Ce que nous n'avons pas, ce sont les valeurs applicationId et le privateKey qui est en fait un fichier.

Dans le tableau de bord Nexmo, cliquez sur Messages et envoi et procédez à la création d'une nouvelle application.

Create messages application

Donnez un nom à l'application et indiquez l'URL de chacun des webhooks que vous venez de créer. Si vous testez encore localement, envisagez d'utiliser ngrok pour établir un tunnel vers localhost afin de pouvoir continuer à tester sans déployer votre application. Choisissez de générer une nouvelle paire de clés privée et publique et déplacez la clé privée téléchargée dans votre répertoire de projet Node.js.

Lorsque vous consultez les applications que vous avez créées dans le tableau de bord Nexmo, vous devez avoir accès à l'identifiant de l'application que nous venons de créer. Fournissez à la fois l'identifiant de l'application et le chemin d'accès à la clé privée dans la variable nexmo qui existe dans notre projet Node.js.

En théorie, tant que vous servez l'application webhook, vous avez deux options pour envoyer des messages depuis GitLab :

1. Vous pouvez créer un autre point de terminaison qui utilise le SDK JavaScript pour l'envoi.

2. Vous pouvez utiliser cURL, mais aussi générer un JWT.

La plus simple des deux options consiste à simplement ajouter un autre point de terminaison à l'application webhook, quelque chose que GitLab peut exécuter en cas d'échec car le SDK JavaScript gère automatiquement la génération des JWT.

Dans le projet Node.js, incluez les éléments suivants :

server.post("/notify", (request, response, next) => {
    nexmo.channel.send(
        { type: "sms", number: request.body.recipient },
        { type: "sms", number: request.body.sender },
        {
            content: {
                type: "text",
                text: request.body.message
            }
        },
        (error, data) => {
            if(error) {
                return response.status(500).send(error);
            }
            response.send(data);
        },
        { useBasicAuth: true },
    );
});

Dans le scénario ci-dessus, les informations relatives au destinataire et à l'expéditeur, ainsi que les informations relatives au message, sont envoyées avec la demande. Ensuite, l'application enverra le message et les webhooks seront utilisés dans le processus.

Si nous devions mettre à jour notre configuration GitLab CI, elle pourrait ressembler à ceci :

image: "alpine:latest"

stages:
  - build
  - notify

build:
  stage: build
  script: 
    - exit 1

notify:
  stage: notify
  script:
    - apk add curl
    - curl -X "POST" "http://HOST/notify" -H 'content-type: application/json' -d '{ "sender": "15404161937", "recipient": "${to}", "message": "${CI_PROJECT_NAME} ${CI_COMMIT_SHORT_SHA} Failed!" }'
  when: on_failure

Dans la configuration ci-dessus, l'application Node.js est utilisée et une charge utile JSON est envoyée. Les informations contenues dans la charge utile sont les données qui ont été précédemment ajoutées en tant que variables de pipeline pour le projet GitLab.

N'oubliez pas qu'avec l'API Messages, vous pouvez utiliser des techniques de messagerie autres que le SMS, même si le SMS était à la base de cet exemple.

Conclusion

Vous venez de voir comment inclure des notifications SMS à votre pipeline d'intégration et de déploiement continus en utilisant Nexmo et GitLab. Bien que nous n'ayons pas créé un projet très extravagant dans ce tutoriel, les concepts utilisés pourraient facilement être repris dans un projet plus complexe. Le point ici est que vous pouvez prendre vos informations Nexmo, créer des variables d'environnement pour votre pipeline, et mettre en place une étape d'échec pour notifier votre équipe par SMS.