DEV Community

giveitatry
giveitatry

Posted on

How to Send GitLab CI/CD Pipeline Notifications to Telegram

#cicd #tutorial #automation #devops

Automating notifications for your CI/CD pipeline is a great way to keep your team informed about the status of builds. Telegram, with its simple bot API, is a convenient platform to send these alerts. This guide will walk you through creating a Telegram bot, setting up GitLab CI/CD, and configuring notifications for both successful and failed builds.

Table of Contents

  1. Prerequisites
  2. Creating a Telegram Bot
  3. Finding Your Chat ID
  4. GitLab CI/CD Variables
  5. Configuring GitLab CI/CD
  6. Sending Telegram Messages from CI/CD
  7. Advanced Tips

1. Prerequisites

Before you start, make sure you have:

  • A GitLab project with CI/CD enabled.
  • A Telegram account.
  • Basic understanding of GitLab CI/CD pipelines.

2. Creating a Telegram Bot

Telegram uses bots to interact with external services. To create a bot:

  1. Open Telegram and search for @BotFather.
  2. Start a chat and send the command /newbot.
  3. Follow the instructions: give your bot a name and a username.
  4. Once created, BotFather will provide you with an API token. Example: 
   123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
Enter fullscreen mode Exit fullscreen mode

This token will allow GitLab to send messages through your bot.

Keep this token secret, as anyone with it can send messages from your bot.

3. Finding Your Chat ID

To send messages, the bot needs a chat ID:

  1. Open a conversation with your bot (or add it to a group chat).
  2. Send any message to the bot.
  3. Open your browser and go to: 
   https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
Enter fullscreen mode Exit fullscreen mode
  1. Look for the "chat":{"id":<number>} field in the JSON response. Example: 
   "chat": { "id": 123456789, "first_name": "John", ... }
Enter fullscreen mode Exit fullscreen mode

This number is your TELEGRAM_CHAT_ID.

4. GitLab CI/CD Variables

GitLab provides several built-in variables, and you can also define custom ones for security and convenience.

Built-in GitLab CI/CD Variables

Variable Description
CI_PROJECT_NAMESPACE Namespace (group/user) of the project
CI_PROJECT_NAME Name of the GitLab project
GITLAB_USER_NAME Name of the user who triggered the pipeline
CI_COMMIT_BRANCH Branch name of the current commit
CI_PIPELINE_URL URL to the running pipeline

Custom Variables

Add these in GitLab Settings → CI/CD → Variables:

Variable Value
TELEGRAM_TOKEN Your bot API token
TELEGRAM_CHAT_ID The chat ID number

Mark these variables as protected if you only want them to be available on protected branches.

5. Configuring GitLab CI/CD

Create or update your .gitlab-ci.yml to include a notify stage:

stages:
  - build
  - test
  - notify
Enter fullscreen mode Exit fullscreen mode

This ensures that notification jobs run after the main pipeline stages.

6. Sending Telegram Messages from CI/CD

You can use curl to send messages through the Telegram Bot API. Here’s how to configure jobs for success and failure notifications.

Success Notification Job 

telegram_notify_success:
  stage: notify
  image: curlimages/curl:8.15.0
  variables:
    GIT_STRATEGY: none
  script:
    - |
      curl -s -X POST https://api.telegram.org/bot${TELEGRAM_TOKEN}/sendMessage \
      -d chat_id=${TELEGRAM_CHAT_ID} \
      -d text="✅ Build and push for *$CI_PROJECT_NAMESPACE/$CI_PROJECT_NAME* by $GITLAB_USER_NAME succeeded on branch *$CI_COMMIT_BRANCH* :) [Check logs]($CI_PIPELINE_URL)" \
      -d parse_mode=Markdown
Enter fullscreen mode Exit fullscreen mode

Failure Notification Job 

telegram_notify_failure:
  stage: notify
  image: curlimages/curl:8.15.0
  variables:
    GIT_STRATEGY: none
  script:
    - |
      curl -s -X POST https://api.telegram.org/bot${TELEGRAM_TOKEN}/sendMessage \
      -d chat_id=${TELEGRAM_CHAT_ID} \
      -d text="❌ Build and push for *$CI_PROJECT_NAMESPACE/$CI_PROJECT_NAME* by $GITLAB_USER_NAME failed on branch *$CI_COMMIT_BRANCH* :( [Check logs]($CI_PIPELINE_URL)" \
      -d parse_mode=Markdown
  when: on_failure
Enter fullscreen mode Exit fullscreen mode

Key Notes:

  • when: on_failure ensures this job only runs if the pipeline fails.
  • parse_mode=Markdown allows basic formatting in Telegram messages.

7. Advanced Tips

  • Single Reusable Notification Job: You can combine success and failure notifications using script logic, reducing duplication.
  • MarkdownV2: If you need more formatting options, switch to parse_mode=MarkdownV2.
  • Testing: Always test your bot manually first to ensure the messages appear correctly.
  • Security: Never commit your TELEGRAM_TOKEN or CHAT_ID to Git. Use protected CI/CD variables instead.

8. Conclusion

With this setup:

  • Your team gets instant notifications about build success or failure.
  • Telegram provides a quick, mobile-friendly way to monitor CI/CD pipelines.
  • GitLab CI/CD variables make it easy to include detailed info about the build, branch, and author.

Top comments (0)