Español
El bot cuenta con un archivo config.json que contiene la configuración inicial.
Las keys que se usen variarán según la o las directivas que se quieran ejecutar, sin embargo hay 3 keys que deberían ser comunes:
-
channel: El canal a enviar los mensajes del bot. -
directives: Las directivas a ejecutar. -
teamMembers: Relación nombre de github-ID de Slack. Esto es para generar menciones en los mensajes.
Además el bot consume 3 variables de entorno, que son obligatorias para el funcionamiento del mismo:
-
GITHUB_API_URI: la url a la API v4 de github. -
GITHUB_AUTH_TOKEN: El token de github (como obtenerlo (en inglés)). Se recomienda que el token tenga permisos de lectura sobre todo. Permisos de escritura no son recomendados a menos que una directiva lo requiera -
SLACK_BOT_TOKEN: El token de tu bot de slack (como obtenerlo (en inglés)).
Usando como ejemplo la funcionalidad actual de notificador de PRs, este sería un archivo config.json valido:
{
"repositories": [
"repo1-ejemplo",
"repo2-ejemplo"
],
"channel": "tu-canal-de-slack",
"labelsToAvoid": ["label-a-filtrar"],
"directives": ["PRReminder"],
"teamMembers": {
"Pepe Juan": "ULTNJDKSJ",
"Mario Borges": "ULFLJGLSO"
}
}
En este caso, las keys repositories y labelsToAvoid son usadas por la directiva PRReminder, aunque podrían ser usadas por otras directivas.
El bot hoy en día funciona básicamente como un script, ya que no se levanta un server, si no que se ejecuta index.js con Node y se corren las directivas configuradas.
Para desarrollar una nueva directiva y probarla, es recomendable crear un Workspace de Slack propio de testeo, instalar ahí una app y luego en un archivo .env en el root del proyecto declarar las variables de entorno obligatorias.
Con eso ya podemos instalar las dependencias del proyecto con yarn install y luego utilizar yarn dev para ejecutar el bot, o yarn watch para ejecutarlo con nodemon y cada vez que se haga un cambio, se ejecute automáticamente.
En este caso para hacer el deploy se eligió Heroku ya que es muy simple y tiene herramientas (también muy simples) para generar un scheduler que ejecute nuestro bot cuando necesitemos.
Realizar el deploy en Heroku es muy simple y podemos encontrarlo en su documentación
Los pasos a seguir son (la instalación es en Ubuntu, para otros SO ver aquí):
Deberán ejecutarse estos comandos dentro de la carpeta del proyecto
$ sudo snap install --classic heroku
# este comando puede obviarse si Heroku ya se encuentra instalado
$ heroku login
# ingresar credenciales de la cuenta de Heroku
$ heroku create
# Esto crea la app en Heroku
$ git push heroku master
# Aquí pusheamos al remote de Heroku para que este buildee y haga el deploy de la app
Una vez ya tenemos nuestra app en Heroku, ahora tenemos que configurarla
Como primera instancia, ingresaremos al dashboard de Heroku y seleccionamos nuestra app.
Esto es para evitar que se ejecute nuestro bot de manera no controlada, ya que Heroku reinicia los Dynos cada un tiempo y provoca que haya ejecuciones que nosotros no queremos.
Dentro de la configuración de nuestra app, ingresaremos a Configure Dynos
Allí deberemos clickear en el icono de editar (lápiz) y clickear en el switch, quedando el Dyno desactivado
El scheduler es un addon que nos permitirá crear un temporizador para nuestro bot y así poder ejecutarlo de manera controlada (por ejemplo, solamente días de semana a ciertos horarios)
Para esto en la pantalla principal de nuestra app iremos a Configure Add-ons
Buscaremos el add-on Advanced Scheduler y lo instalaremos
Un modal aparecerá y al presionar Provision nos instalará el add-on
Al tenerlo instalado y clickear sobre su nombre, ingresaremos a la configuración del add-on para crear un nuevo Trigger
Aquí deberemos ponerle un nombre, el comando a ejecutar y tipo de trigger.
El comando a ejecutar es: node ./dist/index.js. Esto va a ejecutar index.js que contiene la lógica de inicio de nuestro bot.
El tipo de trigger deberá ser Recurring para que nuestro bot se ejecute continuamente según la rutina que nosotros le pondremos, o One-off si es para solo una ejecución.
Luego deberemos agregar la rutina de ejecución. Donde tenemos dos opciones:
- Schedule helper: que nos permitirá agregar una rutina diaria o mensual a cierta hora.
- Cron expression (recomendado): que nos permitirá agregar una expresión cron que tiene una alta flexibilidad al poder configurar una rutina con minutos, hora, días, etc.
IMPORTANTE: tener en cuenta que el horario está en UTC, por lo que hay que sumarle 3 horas a la ejecución. Ejemplo: Si quiero que se ejecute el bot a las 9 am (hora argentina), deberé configurar que se ejecute a las 12 pm (hora UTC). Una herramienta para comparar horarios es Time.is
En este caso utilizamos una expresión Cron que nos permite ejecutar el script de lunes a viernes, a las 9:30, 12:30 y 15:30 hs.
30 12,15,18 * * 1,2,3,4,5
Ponemos el State a Active y luego presionamos Save
Listo! nuestro scheduler está configurado
Ya con el scheduler configurado, deberemos configurar las variables de entorno para que nuestro bot pueda funcionar.
En la página principal de la app, iremos a Settings y presionaremos en Reveal Config Vars
Y se deberán agregar las siguientes variables:
GITHUB_API_URI = https://api.github.com/graphql
GITHUB_AUTH_TOKEN = TOKEN DE GITHUB
SLACK_BOT_TOKEN = TOKEN DEL BOT DE SLACK
YARN_PRODUCTION = false
NPM_CONFIG_PRODUCTION = false
IMPORTANTE: Las últimas dos keys NPM_CONFIG_PRODUCTION y YARN_PRODUCTION son necesarias para evitar el comportamiento default de Heroku y eliminar las devDependencies al buildear el proyecto. Ya que esto elimina también el CLI de Babel y no nos permite ejecutar la transpilación de nuestro bot
Las variables deberían quedar así:
Una vez finalizado esto nuestro, felicitaciones, el bot se encuentra totalmente funcional y listo para ser ejecutado con la rutina que configuraste!