Crea perfettamente un Bot Slack per invocare le Azioni di GitHub tramite Hubot

Tutorial

Se si utilizza GitHub Actions come pipeline di compilazione e rilascio e il proprio team utilizza anche Slack, sapevate che non è nemmeno necessario abbandonare Slack? Creare un bot di Slack per richiamare i flussi di lavoro di GitHub Actions direttamente da Slack in modo automatico!

In questo tutorial, imparerai come configurare un nuovo chatbot di Slack utilizzando lo strumento di creazione di bot chiamato Hubot e avviare automaticamente un flusso di lavoro di GitHub Actions per distribuire il codice su un server.

Iniziamo!

Prerequisiti

Questo tutorial sarà una dimostrazione pratica. Se desideri seguire, assicurati di avere quanto segue:

  • 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.
  • Credenziali SSH per connettersi al server su cui verrà distribuito il codice.
  • A code editor of your choice that understands YAML like Visual Studio Code.

Correlato:Automazione delle azioni Git lato client con Git Hooks

Creazione di un progetto e flusso di lavoro di GitHub Actions

Prima di poter richiamare rapidamente i flussi di lavoro di GitHub Actions da Slack, è necessario creare il flusso di lavoro.

Per creare il flusso di lavoro, creiamo una cartella di progetto in cui verranno inseriti tutti i file con cui lavoreremo.

Correlato:Come avviare la configurazione di GitHub in Visual Studio Code!

1. Apri la tua applicazione terminale preferita.

2. Ora esegui la serie di comandi di seguito per creare la cartella del progetto chiamata Hubot e navigare al suo interno. 

mkdir ~/Hubot # Crea una directory chiamata Hubot
cd ~/Hubot    # Cambia directory in Hubot

3. Successivamente, esegui npm init per creare un file package.json di Node.JS. Eseguire npm init crea un progetto Node.JS standard che include il file package.json che contiene varie informazioni sul progetto e su eventuali pacchetti NPM dipendenti. 

npm init      # Inizializza il file package.json

4. Ora, crea una directory workflows e il file di flusso di lavoro deploy.yml. Il file di flusso di lavoro è una serie di passaggi definiti in una sequenza che le Azioni di GitHub seguiranno.

mkdir .github/workflows && touch deploy.yml

5. Successivamente, definisci ciascuno dei segnreti GitHub che il tuo flusso di lavoro leggerà. Il flusso di lavoro che stai per creare farà riferimento a questi segreti. Poiché avrai bisogno dell’indirizzo del tuo server, del nome utente, della password e della porta del tuo server per SSH, creiamo i segreti GitHub.

Visita questo URL https://github.com/tuonomeutente/tuorepository/settings/secrets/actions dove aggiungerai i segreti GitHub. Sostituisci tuonomeutente con il tuo nome utente GitHub e todorepository con il tuo repository GitHub.

Fai clic sul pulsante Nuovo segreto del repository, come mostrato di seguito, per compilare le informazioni sul segreto che stai aggiungendo.

Adding GitHub Secrets

6. Compila ora il campo Nome e Valore del segreto, quindi fai clic su Aggiungi segreto per salvarlo. La pagina si ridirigerà alla pagina dei segreti GitHub dove vedrai tutti i tuoi segreti. Per aggiungere ulteriori segreti, fai clic sul pulsante Nuovo segreto del repository come hai fatto precedentemente.

Assicurati di salvare i segreti per le variabili fornite con lo stesso nome con cui farai riferimento alle stesse variabili, che sono HOST, USERNAME, PASSWORD e PORT.

Filling up Information for a GitHub Secret
Viewing All GitHub Secrets

7. Infine, apri il file del flusso di lavoro ~/Hubot/.github/workflows/deploy.yml nel tuo editor di codice e copia/incolla il seguente codice. Il codice qui sotto è il flusso di lavoro che verrà eseguito ogni volta che attivi il flusso di lavoro tramite Slack in seguito.

Quando richiami il flusso di lavoro, si verificheranno un paio di azioni:

  • GitHub Actions analizzerà il file di workflow di seguito per connettersi via SSH al host di destinazione definito nel segreto HOST con USERNAME e PASSWORD definiti come segreti.
  • Il workflow scaricherà quindi i contenuti del repository GitHub per un determinato branch ($branchName) eseguendo git pull origin$branchName. Assicurati che il nome del branch contenga il codice che desideri distribuire.
  • Stai utilizzando un Pacchetto di Workflow da GitHub Marketplace chiamato ssh-remote-commands. Questo pacchetto ha un’ottima interfaccia per aggirare dove è necessario fornire solo host, username, password, porta e comando da eseguire in produzione.

Assicurati che il tuo server abbia git installato con le credenziali di accesso necessarie per scaricare il codice dal repository GitHub

# Il nome che verrà referenziato verrà utilizzato molto di più in modo programmato 
name: deploy 
on:
  # L'evento respository_dispatch significa su ogni trigger API, 
  # questo intero file viene eseguito
  repository_dispatch: 
    types: [deploy-service]
# Ci possono essere più lavori, ma attualmente, 
# questo tutorial funzionerà solo su uno
jobs:
  deploy:
    name: Deploy
    # Il nome dell'immagine di base dove vengono eseguiti tutti i codici YAML
    runs-on: ubuntu-latest
    steps:
    - name: executing remote ssh commands using password
      # appleboy/ssh-action@master è un pacchetto open-source 
      # che accede a un server via ssh ed esegue lo script
      uses: appleboy/ssh-action@master
      # Queste sono generalmente le variabili che il pacchetto necessita 
      # per accedere al server ed eseguire lo script
      with:
       # I segreti sono le variabili da 
       # https://docs.github.com/en/actions/security-guides/encrypted-secrets

       # Il tuo host del server memorizzato su segreti github con lo stesso nome HOST
        host: ${{ secrets.HOST }} 
        # Il nome utente del tuo server per il login 
        # che è memorizzato su segreti github con nome USERNAME
        username: ${{ secrets.USERNAME }} 
        # La password del tuo server per il login 
        # che è memorizzata su segreti github con nome PASSWORD        
        password: ${{ secrets.PASSWORD }} 
        # La porta del tuo server per il login 
        # che è memorizzata su segreti github con nome PORT
        port: ${{ secrets.PORT }}  
        # deploy-app.sh può essere qualsiasi cosa, ad esempio puoi tirare il codice da GitHub
        # e riavviare il tuo webserver o le code qualsiasi cosa
        # Assicurati di aver clonato il repository sul tuo server  
        # Puoi eseguire tanti script quanti ne vuoi
        script: git pull origin {{ github.event.client_payload.branch

Eseguire il flusso di lavoro manualmente

Hai ora creato il flusso di lavoro di GitHub Actions da invocare tramite Slack. Ma a questo punto, il tuo codice è solo sulla tua macchina locale. Per avviare il flusso di lavoro, dovrai eseguire il push del codice su GitHub.

Eseguendo la serie di comandi di seguito, dici a git da dove dovrebbe essere pushato e pullato il codice, in questo esempio, dal tuo repository remoto di GitHub. Nel comando git remote add origin qui sotto, sostituisci yourusername e yourrepository con il tuo nome utente e repository di GitHub

# Apri github.com e crea un repository
git init # Inizializza git
git remote add origin https://github.com/yourusername/yourrepository.git
git add . # Aggiunge i file appena creati affinché git li tenga traccia
git commit -m "Created GitHub workflow file"
git push -u origin master

Prima di tutto, testiamo se il tuo codice funziona. Invoca il tuo codice manualmente utilizzando l’utilità curl popolare.

Esegui il comando qui sotto per fare una richiesta post al tuo Repository di GitHub https://github.com/username/repository/dispatches URL per dire a GitHub di attivare un file di flusso di lavoro deploy.yml che hai creato in precedenza. Sostituisci username con il tuo nome utente GitHub effettivo e repository con il tuo repository GitHub.

Sostituisci $github_personal_token nel codice qui sotto con il tuo token personale.

# Effettua una richiesta di post all'URL https://github.com/username/repository/dispatches 
curl-X POST  https://github.com/username/repository/dispatches \
# Aggiunge l'intestazione per accettare il tipo di contenuto
-H 'Accept: application/vnd.github.everest-preview+json' \
# Aggiunge l'intestazione per l'autorizzazione
-H "Authorization: token $github_personal_token" \
# Aggiunge il contenuto json nel corpo della richiesta di post in modo da poter inviare più parametri 
# da questa sezione dati e puoi eseguire varie azioni in base agli argomenti
--data '{"event_type": "deploy-service", "client_payload": {"environment": "'"$1"'", "ref": "'"$2"'"}}' # Puoi passare il nome dell'ambiente e ref come nome del branch in modo che tu sappia su quale branch effettuare il deployment su quale server

Crea un Bot Slack con Hubot

Dal momento che sei stato in grado di attivare manualmente il Workflow delle azioni di GitHub, è un buon inizio. Ora proviamo ad automatizzare gli stessi passaggi manuali tramite il Bot Slack. Creerai un Bot Slack, che ascolta il tuo comando e attiva l’azione di GitHub con gli argomenti.

Hai due opzioni per creare un Bot Slack, o da zero o un pacchetto hubot pre-costruito per gli spazi di lavoro slack. In questo tutorial, utilizzerai un pacchetto Bot pre-costruito chiamato Hubot. Hubot è uno strumento di automazione open source che si integra con servizi di chat come Slack, Discord, Gitter, TeamSpeak, ecc.

Creare un bot personalizzato senza utilizzare un’app come Hubot richiede molto tempo. Perché? Perché dovrai gestire tutti i processi di configurazione, ascolto di webhook e hosting del bot. Quindi, in questo tutorial, utilizzerai l’app Hubot Slack per semplificare tutti questi processi.

Installazione di Hubot con Npm

Poiché stai utilizzando Hubot per creare un Bot Slack, prima scarica ed installa Hubot sul tuo computer locale. Hubot sarà il connettore che collega Slack e le azioni di GitHub.

1. Nel tuo terminale, naviga (cd) nella directory del tuo progetto (~/Hubot). 

cd ~/Hubot

2. Installa globalmente il pacchetto yo e generator-hubot sulla tua macchina locale con il comando npm install qui sotto. Il pacchetto yo ti aiuta ad installare nuovi progetti generando progetti in qualsiasi linguaggio (Web, Java, Python, C#, etc.). Il pacchetto generator-hubot utilizza il pacchetto yo per installare tutte le dipendenze insieme alle configurazioni iniziali.

Una volta installato, puoi eseguire il comando yo da qualsiasi posizione poiché è stato installato globalmente.

npm install -g yo generator-hubot

3. Ora, crea un boilerplate di base di Hubot con il seguente comando. Un boilerplate è una sezione di codice inclusa in molti luoghi. Senza un boilerplate, è sempre necessario scrivere il codice da zero.

Il comando qui sotto crea un boilerplate di base di Hubot nella directory del tuo progetto. Il boilerplate di Hubot collega Slack (--adapter=slack) in modo che il Bot possa ascoltare e rispondere ai messaggi all’interno del canale Slack. yo hubot --adapter=slack

yo hubot --adapter=slack

Aggiunta di Hubot al Tuo Spazio di Lavoro Slack

Ora che Hubot è installato sul tuo computer locale, è necessario configurare Hubot per comunicare con Slack.

Instiamo Hubot nel tuo Spazio di Lavoro Slack.

1. Apri il tuo browser web e vai alle impostazioni amministrative di Slack con l’URL, come https://workspacename.slack.com/admin/settings. Sostituisci workspacename con il nome effettivo del tuo Spazio di Lavoro Slack.

Clicca su Configura applicazioni nnel pannello di sinistra, come mostrato di seguito, in modo da poter cercare Hubot nel marketplace. Slack ha un marketplace dove puoi trovare applicazioni pre-costruite.

Accessing Slack Admin Settings

2. Clicca sulla barra di ricerca, quindi digita hubot per cercare Hubot nel marketplace e seleziona Hubot.

Ora, clicca sul pulsante Aggiungi a Slack, come vedi qui sotto, per aggiungere Hubot al tuo Spazio di Lavoro Slack.

Searching Hubot and Adding it to Slack Workspace

3. Infine, compila alcune informazioni generali sul tuo Bot, come il nome (deployerhubot) e l’icona. Prendi nota del Token API poiché lo utilizzerai successivamente in Hubot Deployer per attivare il Bot nel progetto Hubot che hai creato in precedenza.

Setting up Bot Information and Taking Note of the API Token

Testing dell’integrazione di GitHub Actions Workflow con Slack

Ora hai Hubot installato nel tuo spazio di lavoro Slack, quindi testiamo il bot ascoltando e inviando messaggi al canale. Ma prima devi attivare il Bot.

1. Esegui il comando sottostante all’interno della directory principale del progetto per attivare il Bot per Slack (--adapter slack) dal tuo repository Hubot (./bin/hubot). Assicurati di sostituire $token con il token API annotato in precedenza

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

2. Esegui il comando sottostante per invitare (/invite) il Bot (botusername) nel tuo canale Slack. Sostituisci botusername con il nome del Bot che hai registrato al passo tre della sezione “Aggiunta di Hubot al tuo spazio di lavoro Slack”. 

/invite deployerhubot

Ora, menziona un Bot con un testo su Slack, ad esempio @deployerhubot ping, per verificare se l’integrazione funziona. Se il Bot risponde PONG, come mostrato di seguito, allora sei a posto.

Testing Hubot and Slack Integration

Se il Bot non risponde, vai al tuo repository GitHub nel tuo browser web e fai clic sulla scheda Actions. Puoi identificare quale workflow ha fallito poiché ha un distintivo di controllo rosso tondo. Fai clic sul workflow fallito per vedere cosa ha causato il fallimento e risolvilo.

Viewing Failed Workflows

Ecco, puoi vedere che il fallimento riguarda l’esecuzione di comandi SSH remoti utilizzando la password all’interno di . Dopo aver corretto il flusso di lavoro, torna al passo 3 e verifica se il Bot risponde con PONG.

Navigating to GitHub repository to fix failed workflow

Avvio di un flusso di lavoro GitHub Actions da Slack

Ora che hai attivato il tuo Slack Bot, è il momento di avviare il flusso di lavoro GitHub Actions da Slack!

Hai bisogno della flessibilità di distribuire il ramo dato su un server specifico, come estrarre i codici dal ramo specificato. Insegnerai al Bot a rispondere automaticamente quando qualcuno digita ***@*bot deploy API feature-x to production in un canale Slack. Puoi convalidare il nome dell’ambiente, in modo che in seguito le persone possano distribuire solo in determinati ambienti e rami.

Per automatizzare le risposte del Bot:

1. Crea una directory chiamata ~/Hubot/scripts. La directory ~/Hubot/scripts è dove salverai uno script che attiva il tuo flusso di lavoro GitHub.

2. Nel tuo editor di codice, crea un file chiamato bot.js all’interno della directory ~/Hubot/scripts. Copia il codice qui sotto e incollalo all’interno del file bot.js.

Il codice qui sotto consente al Bot di ascoltare i messaggi nella chat su Slack, attivando quindi il flusso di lavoro per inviare una risposta al canale Slack.

const validServices = ['api','app'];
const validEnvironments = ['production'];
robot.hear (`@${process.env.BOT_ID}`,async (bot) => {
    // Il Bot è interessato solo a ascoltare il messaggio 
    // come @deploy api featurex to production 
    // Configurazione della variabile riutilizzabile
	  const payload = bot.message.text.split(" ")
    const service = payload[2];
    const branch = payload[3];
    const environment = payload[5];
    const username = bot.message.user.name;
    // Informare l'utente che stiamo elaborando
    bot.send(`Roger that! Please wait.`);
// Validare se il comando utilizzato è valido o meno 
// perché l'utente può utilizzare anche comandi non validi 
if(!validateCommand(bot,username,service,branch,environment)) {
      return;
    }
    // Se il comando sembra valido, attivare un flusso di lavoro
    await triggerWorkflow(bot,username,service,environment,branch)
    
    // Informare l'utente che il flusso di lavoro è stato attivato con successo
    bot.send(`Github Action has been triggered successfully`);
  })
  const validateCommand = (bot,username,service,branch,environment) => {
    // Limitare i servizi in quanto gli utenti possono utilizzare servizi non elencati 
    // che cercheranno di attivare il flusso di lavoro e otterranno un errore
    if(!validServices.includes(service)) {
       bot.send(`${service} is not availble, Only ${validServices.join(', ')} are available`);
      return false;
      }
      // Limitare l'ambiente in quanto gli utenti possono utilizzare un elenco di ambienti non validi 
      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 {
      // Questo è lo stesso codice di attivazione manuale del flusso di lavoro convertito 
      // da curl a una richiesta post di JavaScript effettiva
      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. Infine, invia il messaggio @botusername deploy api staging to dev su Slack e vedrai una risposta simile, come mostrato di seguito.

I file di flusso di lavoro possono essere attivati su vari Eventi di GitHub, come l’invio del codice a un certo ramo, la creazione di tag, la creazione di richieste pull, la richiesta di alcuni URL e molti altri.

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

Conclusione

Durante questo tutorial, hai appreso riguardo al Flusso di Lavoro di GitHub, dall’attivazione manuale delle risposte su Slack con codici alla costruzione di un chatbot. Hai anche imparato che avere un chatbot su Slack ti permette di automatizzare compiti invocando il flusso di lavoro delle azioni di GitHub.

Vuoi portare questa nuova conoscenza ad un livello superiore, magari aggiungendo un Bot di Promemoria o creando messaggi interattivi?

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