Athul Cyriac Ajay

College of Engineering Kidangoor

Telegram Bot with GitHub Actions

Originally posted here

Telegram

Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed. It is free to use and extensively hackable. It also has a good bot support system. The API is also easy to implement and has many wrappers for building bots with the API.

GitHub Actions

GitHub Actions is a CI/CD runtime for your GitHub repository. You can run almost anything from scripts to docker containers. You can build, test and deploy your code with GitHub Actions. All these actions are called workflows and workflows differ in the job they’re doing. These maybe test workflows, build ones or deployment ones. You can find all the actions on GitHub in the marketplace

Building the Bot

Prerequisites

  • Basic JavaScript Knowledge
  • Basic GitHub Knowledge
  • Telegram Account

There are templates for building actions. Here we’re gonna start from scratch

Environment Setup

  • Node, You can download node from their website
  • NPM comes with node, so you don’t have to worry about it.
  • Initialize the Project
$ git init ## initialize a new git repository for version management
---
$ npm init
  • dotenv, Dotenv can be downloaded via
$ npm i dotenv
---
$ yarn add dotenv
  • node-telegram-bot-api, node-telegram-bot-api is a simple wrapper for building telegram bots. You can download it via
$ npm i node-telegram-bot-api
---
$ yarn add node-telegram-bot-api
  • @zeit/ncc, NCC is a Simple CLI for compiling a Node.js module into a single file, together with all its dependencies, GCC-style. It’s a dev dependency and can be downloaded
yarn add --dev @zeit/ncc
---
npm i -D @zeit/ncc

Folder Structure

The dist folder will be automatically created. action.yml will be made

.
├── dist
│   └── index.js
├── index.js
├── action.yml
├── README.md
└── package.json
  • index.js is the file we’re defining the bot
  • action.yml is the file we’ll define the action and it’s behaviours

Making the Bot

We need to get an API bot token from telegram. For that Go to Telegram and Search for Botfather. It’s a bot. Create a new bot with the /newbot command and get the API key. We’ll need that, also talk to jsondump bot and get your chat id. The output may be like this, so

{
  "update_id": 143943779,
  "message": {
    "message_id": 181575,
    "from": {
      "id": 123456 // this is what we need
      "is_bot": false,
      "first_name": "Tg Name",
      "username": "TG Username",
      "language_code": "en"
    },
    "chat": {
      "id": 123456,
      "first_name": "Tg Name",
      "username": "TG Username",
      "type": "private"
    },
    "date": 1584119424,
    "text": "message"
  }
}

This will be needed for further use and We need to add it to the repo secrets which can be found in the repo settings. Be careful to add it as token and chat like as shown below

Writing the Action and Building the Bot

Fire up the terminal/cmd and make a new folder. Install the dependencies. Run the following command

$ touch index.js action.yml

Open your favourite text editor within the folder or with the file. We’ll define the bot in index.js

require("dotenv").config
const Bot = require('node-telegram-bot-api');
const {
    INPUT_STATUS: ipstatus,
    INPUT_TOKEN: tgtoken,//Telegram api token
    INPUT_CHAT: chatid,// Telegram Chat ID
    INPUT_IU_TITLE: ititle,// Issue title
    INPUT_IU_NUM: inum,// Issue Number
    INPUT_IU_ACTOR: iactor,// Issue made by
    INPUT_IU_BODY: ibody,// Issue Body
    INPUT_PR_NUM: pnum,// PR Number
    INPUT_PR_STATE: prstate,// PR Opened, reponed or closed
    INPUT_PR_TITLE: ptitle,// PR Title
    INPUT_PR_BODY: pbody,// Body of the PR
    GITHUB_EVENT_NAME: ghevent,// Name of the trigger event
    GITHUB_REPOSITORY: repo,// Repository the trigger was made from
    GITHUB_ACTOR: ghactor,// User who triggered the action
    GITHUB_SHA: sha,// Commit ID
    GITHUB_WORKFLOW: ghwrkflw// Workflow Name
} = process.env;

const bot = new Bot(tgtoken)

First, we’re defining the dotenv for config and initializing Telegram Bot. Here we’re defining the alias variables for the environment variables. You might notice an INPUT_ for almost every environment variable, this is because GitHub Actions pass the env variable with an INPUT prefix. Other env variables are action’s default environment variables. Then we initialized the bot with the API token.

GitHub actions could be triggered with Issues, Pull Request or Pushes. You can find the trigger events here. Here we’re gonna get a message from the bot when an Issue or Pull Request or a Push event has happened.

const evresp = (gevent) => {
  switch (gevent) {
    case 'issues':
      return `
❗️❗️❗️❗️❗️❗️
        
Issue ${prstate}

Issue Title and Number  : ${ititle} | #${inum}

Commented or Created By : \`${iactor}\`

Issue Body : *${ibody}*

[Link to Issue](https://github.com/${repo}/issues/${inum})
[Link to Repo ](https://github.com/${repo}/)
[Build log here](https://github.com/${repo}/commit/${sha}/checks)`;
    case 'pull_request':
      return `
🔃🔀🔃🔀🔃🔀
PR ${prstate} 
        
PR Number:      ${pnum}
        
PR Title:       ${ptitle}
        
PR Body:        *${pbody}*
        
PR By:          ${ghactor}
        
[Link to Issue](https://github.com/${repo}/pull/${pnum})
[Link to Repo ](https://github.com/${repo}/)
[Build log here](https://github.com/${repo}/commit/${sha}/checks)`;
    default:
      return `
⬆️⇅⬆️⇅
            
ID: ${ghwrkflw}
        
Action was a *${ipstatus}!*
        
\`Repository:  ${repo}\` 
        
On:          *${ghevent}*
        
By:            *${ghactor}* 
        
Tag:        ${process.env.GITHUB_REF}
        
[Link to Repo ](https://github.com/${repo}/)
            `;
  }
};

In these lines of code, we’re just initializing a switch statement for the responses. We’re also declaring an anonymous function to use the switch responses via a function later. We’re using all the defined variables in the switch. You can check the trigger Events to get how the event is triggered and what keyword should be used.

Now for the last part of the Js file, we just take the response from the switch and assign it to a constant. Then we use the sendMessage function of the node-telegram-bot-api to send the message to the bot with the chatid and the output as the arguments.

const output = evresp(ghevent);

bot.sendMessage(chatid,output,{parse_mode : “Markdown”})

Compiling and Minifying the Js code

Since we have installed @zeit/ncc and this is used for the making the whole program with all the APIs to a single file and we need to use NCC for that. We just need to run

yarn run ncc build index.js -C -m -o dist

or you might wanna add the following to you package.json file, and run npm run test to compile and minify the code.

"scripts": {
    "test": "ncc build index.js -C -m -o dist"
  },

This will create a dist folder with and index.js file which contains the compiled code.

Making it a valid action

For making this Js file a valid action, we need to add an action.yml file. The action.yml for this action is like this

name: 'Action Name'
description: 'Action Descreption'
author: '<author name>'
inputs:
  chat:
    description: 'Chat to send: chat id or @channel_name'
    required: true
  token:
    description: 'Telegram Bot token'
    required: true
  status:
    description: 'Job status'
    required: true
  iu_title:
    description: 'Issue Title'
    default: $
  iu_num:
    description: 'Issue Number'
    default: $
  iu_actor:
    description: 'Issue Triggerer'
    default: $
  iu_com:
    description: 'Issue Comment'
    default: $
  pr_state:
    description: 'State of the PR'
    default: $
  pr_num:
    description: 'PR Number'
    default: $
  pr_title:
    description: 'Title of the PR'
    default: $
  pr_body:
    description: 'Body/Contents of the PR'
    default: $
runs:
  using: 'node12'
  main: 'dist/index.js'
branding:
  icon: 'repeat'
  color: 'green'

Here we’re defining the Input variables to be loaded for the action in GitHub’s runtime environemt. All these default data are taken from the response of the webhooks which are send by GitHub when a trigger event is occured. You can find out more in the Action Documentation Here.

runs:
  using: 'node12'
  main: 'dist/index.js'

Here we are defining that this is a node action and should run in an environment with node, and the file which should be run, here the index.js file in the dist folder. That should do it. Create a new commit and push it to a repo. Create a new tag and this action will appear in the marketplace.

Defining a workflow to test your action

GitHub Action workflows are defined using the .yml syntax. Here is an example of a sample workflow for this action

name: <Workflow Name>

on:
  push:
  pull_request:
    types: [opened, closed]
  issues:
    types: [opened, closed, reopened]
jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: <AnyName>
        uses: <username>/<repo>@master
        if: always()
        with:
          chat: $
          token: $
          status: $

The Complete code for the bot is

//Initializing dotenv and the bot
require('dotenv').config;
const Bot = require('node-telegram-bot-api');
// aliasing the environment variables
const {
  INPUT_STATUS: ipstatus,
  INPUT_TOKEN: tgtoken, //Telegram api token
  INPUT_CHAT: chatid, // Telegram Chat ID
  INPUT_IU_TITLE: ititle, // Issue title
  INPUT_IU_NUM: inum, // Issue Number
  INPUT_IU_ACTOR: iactor, // Issue made by
  INPUT_IU_BODY: ibody, // Issue Body
  INPUT_PR_NUM: pnum, // PR Number
  INPUT_PR_STATE: prstate, // PR Opened, reponed or closed
  INPUT_PR_TITLE: ptitle, // PR Title
  INPUT_PR_BODY: pbody, // Body of the PR
  GITHUB_EVENT_NAME: ghevent, // Name of the trigger event
  GITHUB_REPOSITORY: repo, // Repository the trigger was made from
  GITHUB_ACTOR: ghactor, // User who triggered the action
  GITHUB_SHA: sha, // Commit ID
  GITHUB_WORKFLOW: ghwrkflw, // Workflow Name
} = process.env;

const bot = new Bot(tgtoken);
// Function to return the response for the specific trigger
const evresp = (gevent) => {
  switch (gevent) {
    //Switch statement for issues
    case 'issues':
      return `
❗️❗️❗️❗️❗️❗️
        
Issue ${prstate}

Issue Title and Number  : ${ititle} | #${inum}

Commented or Created By : \`${iactor}\`

Issue Body : *${ibody}*

[Link to Issue](https://github.com/${repo}/issues/${inum})
[Link to Repo ](https://github.com/${repo}/)
[Build log here](https://github.com/${repo}/commit/${sha}/checks)`;
    // Switch statement for Pull Requests
    case 'pull_request':
      return `
🔃🔀🔃🔀🔃🔀
PR ${prstate} 
        
PR Number:      ${pnum}
        
PR Title:       ${ptitle}
        
PR Body:        *${pbody}*
        
PR By:          ${ghactor}
        
[Link to Issue](https://github.com/${repo}/pull/${pnum})
[Link to Repo ](https://github.com/${repo}/)
[Build log here](https://github.com/${repo}/commit/${sha}/checks)`;
    default:
      // switch statement for Pushes
      return `
⬆️⇅⬆️⇅
            
ID: ${ghwrkflw}
        
Action was a *${ipstatus}!*
        
\`Repository:  ${repo}\` 
        
On:          *${ghevent}*
        
By:            *${ghactor}* 
        
Tag:        ${process.env.GITHUB_REF}
        
[Link to Repo ](https://github.com/${repo}/)
            `;
  }
};
// assigning the output to a variable
const output = evresp(ghevent);
// sending the message
bot.sendMessage(chatid, output, { parse_mode: 'Markdown' });

You can try out many different items using actions and this is just a sample action to get you started. Maybe sending Cat GIFs if the build succeded on the pull request or sending a welcome message to a first time contributor. You imagination is the limit😄 and Never Stop being ⚡️