GitLab-Telegram Bot

This bot will handle the following events and inform you via Telegram about those events:

• Issues opened, re-opened & closed
• Merge requests are opened, re-opened, closed or merged
• Failing pipelines
• Successful deployments
• New releases

Production

We will first explain how to use this setup in production. See below for running a development setup.

Setup

You need to set some settings using environment variables, for that we use the .env file. You can use the .env.example file as template.

cp .env.example .env

Adapt the .env file to your settings.

In production we use Docker, see docker-compose.yml file to start the Docker container leveraging Docker Compose. It's advised to run the bot behind a reverse proxy (eg. Nginx).

Start the container using: docker compose up or start in the background using: docker compose up -d.
Note: If you installed Docker Compose manually, the script name is docker-compose instead of docker compose.

Testing

Some test events will not listen to the triggers (since it will not contain the right trigger information). But the Releases events should work from the Test drop-down menu (last option).

For testing purpose you could disable the Telegram integration and use a fake telegram bot. To use the fake bot set the TELEGRAM_ENABLED environment variable to false:

export TELEGRAM_ENABLED=false

Adding Webhook

Add your URL as Webhook in your GitLab project, in your GitLab repository go to: Settings -> Webhooks in the menu.

GitLab Secret token is also required!
You need to store the same GitLab secret token in your .env file using the variable name GITLAB_SECRET_TOKEN.

Add the public URL towards this GitLab-Telegram bot, be sure to add /gitlab to the end of the URL (eg.https://bot.mydomain.com/gitlab, when bot is running behind a reverse proxy).
Since the route ending with /gitlab is mapped to the HTTP GitLab POST Webhook events.

Enable the following triggers or the bot will not work as expected:

• Issues Events
• Merge Requests Events
• Pipeline Events
• Deployment Events
• Releases Events

Also notice you could unselect the Push events (which is enabled by default).

Development

Requirements

• Node.js LTS
• pnpm

Install prerequisites

Node.js:

curl -sL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

pnpm package manager:

curl -fsSL https://get.pnpm.io/install.sh | sh -

Getting started

Assuming you already fulfilled the requirements above.

1. Clone the project: git clone git@gitlab.melroy.org:melroy/gitlab-bot.git
2. Install the Node.JS dependencies via: pnpm install
3. Prepare the .env (see .env.example file), like setting the URL, TELEGRAM_TOKEN, GITLAB_SECRET_TOKEN and GITLAB_TELEGRAM_CHAT_MAPPING environment variables.
4. To start the bot by executing: pnpm start

The GITLAB_TELEGRAM_CHAT_MAPPING environment variable is a JSON object (with key/value pairs). The key is the GitLab project ID (eg. 42) and the value is the corresponding Telegram chat ID (@telegramgroup). You can have multiple key/value pairs in a single object to serve multiple projects and telegram channels/groups.

Hint: You can also disable the Telegram integration and use a fake Telegram bot. To use the fake bot set: TELEGRAM_ENABLED=false in the .env file.