Napkin Tools: Actions Telegram Notify

An action for sending notifications to Telegram about the status of a Workflow execution in GitHub Actions, GitLab CI/CD, or any GitHub Actions-compatible CI/CD system (e.g. Gitea Actions).

The action automatically detects your CI provider and adapts its event parsing — no configuration changes needed.

Русская версия

Table of Contents

• Features
• Requirements
• Execution Arguments
  • status Values
  • notify_fields Values
• GitHub Actions Usage
  • Push Event
    • Field Breakdown
  • Pull Request Event
  • Pull Request Review Event
  • Workflow Dispatch Event
• GitLab CI/CD Usage
  • GitLab Push Event
  • GitLab Merge Request Event
  • GitLab Tag Push
  • Manual / Web / Schedule Trigger
• Notification Examples
  • Notification for Successful Workflow Completion in a Push Event
  • Notification for Opening a Pull Request
  • Notification for Closing a Pull Request
  • Notification for Merging a Pull Request
  • Notification for Workflow Dispatched
• Author
• Support
• Contributors
• License

Features

• Sends status updates to Telegram (e.g., success, failure, canceled).
• Customizable notifications with a title, message, and footer.
• Includes additional fields such as commit author, repository, workflow name, and more.
• Supports Push, Pull Request, Pull Request Review, and Workflow Dispatch events on GitHub Actions.
• Supports push, tag push, merge_request, manual/web/schedule/trigger events on GitLab CI/CD.
• Automatically generates a button with a link to the Commit, Pull Request, or Repository in the notification.
• Provider auto-detection — the same Docker image works on GitHub and GitLab without configuration changes.
• Backward compatible — all existing GitHub Actions workflows continue to work exactly as before.

Requirements

To use Actions Telegram Notify, you need:

• Telegram Bot Token (can be created via BotFather).
• Telegram Chat ID:
  • For direct messages from the bot: 1234567.
  • For a small group: -1234567.
  • For a large group/supergroup: -1001234567.
  • Important:
    • For direct messages, you need to start a chat with the bot.
    • For groups, add the bot and grant it minimal admin rights to send messages.
• (Optional) Telegram Chat Thread ID – required for sending messages to a specific topic in a supergroup.

Execution Arguments

Name	Required	Description
token	Yes	Telegram Bot Token. Use GitHub Secrets / GitLab CI Variables for secure storage.
chat_id	Yes	Telegram Chat ID. Use GitHub Secrets / GitLab CI Variables for secure storage.
api_url	No	Custom Telegram Bot API URL. Use secrets for secure storage.
thread_id	No	Telegram Chat Thread ID.
status	No	Workflow status, retrieved from ${{ job.status }} or set manually (e.g., pending). Defaults to info if not specified.
title	No	Custom title text for the notification. Defaults to a general message.
message	No	Custom message text to include in the notification.
footer	No	Text to append at the end of the notification.
notify_fields	No	Comma-separated list of additional fields to include. See notify_fields Values for details.
proxy_url	No	Proxy server URL for routing requests (e.g., http://user:***@127.0.0.1:8080 or socks5://ip:port).

status Values

Statuses apply to the Push event.

Value	Description
success	Workflow completed successfully.
failure	Workflow failed.
cancelled	Workflow was canceled.
pending	Workflow is in progress.
info	Informational status.

notify_fields Values

Field	Event	Description
actor	Push, Pull Request, Pull Request Review, Workflow Dispatch	Username with a profile link who triggered the Workflow.
repository	Push, Pull Request, Pull Request Review, Workflow Dispatch	Repository name with a link where the Workflow is running.
workflow	Push, Pull Request, Pull Request Review, Workflow Dispatch	Name of the running Workflow.
branch	Push	Branch where the Workflow was triggered.
commit	Push	First line of the commit message.
repo_with_tag	Push	Repository name with a tag.

GitHub Actions Usage

Push Event

name: CI

on:
  push:

jobs:
  notify:
    runs-on: ubuntu-latest

    steps:
      - name: Run Actions Telegram Notify
        uses: proDreams/actions-telegram-notifier@main
        if: always()
        with:
          token: ${{ secrets.TELEGRAM_BOT_TOKEN }}
          chat_id: ${{ secrets.TELEGRAM_CHAT_ID }}
          status: ${{ job.status }}
          notify_fields: "actor,repository,workflow,branch,commit"
          message: "Test message."
          footer: "Test footer"

Field Breakdown

• name - Specifies the step name (optional).
• uses - Specifies the Action to use. It is recommended to use the latest version from the main branch.
• if - Defines the execution condition:
  • always() - Always runs, regardless of Workflow status (recommended).
  • cancelled() - Runs only if the Workflow was canceled.
  • failure() - Runs only if the Workflow failed.
  • success() - Runs only if the Workflow was successful.
• with - List of input parameters required for execution. See Execution Arguments for details.

Pull Request Event

name: CI

on:
  pull_request:
    types:
      - closed
      - opened

jobs:
  notify:
    runs-on: ubuntu-latest

    steps:
      - name: Run Actions Telegram Notify
        uses: proDreams/actions-telegram-notifier@main
        if: always()
        with:
          token: ${{ secrets.TELEGRAM_BOT_TOKEN }}
          chat_id: ${{ secrets.TELEGRAM_CHAT_ID }}
          status: ${{ job.status }}
          notify_fields: "actor,repository,workflow"

Pull Request Review Event

name: CI

on:
  pull_request_review:
    types:
      - submitted

jobs:
  notify:
    runs-on: ubuntu-latest

    steps:
      - name: Run Actions Telegram Notify
        uses: proDreams/actions-telegram-notifier@main
        if: always()
        with:
          token: ${{ secrets.TELEGRAM_BOT_TOKEN }}
          chat_id: ${{ secrets.TELEGRAM_CHAT_ID }}
          status: ${{ job.status }}
          notify_fields: "actor,repository,workflow"

Workflow Dispatch Event

name: CI

on:
  workflow_dispatch:
    inputs:
      custom_input:
        description: 'Custom Input'
        required: false

jobs:
  notify:
    runs-on: ubuntu-latest

    steps:
      - name: Run Actions Telegram Notify
        uses: proDreams/actions-telegram-notifier@main
        if: always()
        with:
          token: ${{ secrets.TELEGRAM_BOT_TOKEN }}
          chat_id: ${{ secrets.TELEGRAM_CHAT_ID }}
          status: ${{ job.status }}
          notify_fields: "actor,repository,workflow"

GitLab CI/CD Usage

The action works in GitLab CI/CD via a Docker image — no uses: syntax, just image: + variables:.

Important: Keep your TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID in GitLab CI/CD Variables (Settings → CI/CD → Variables) with the Masked flag.

GitLab Push Event

notify-push:
  image: ghcr.io/prodreams/actions-telegram-notifier:latest
  variables:
    INPUT_TOKEN: $TELEGRAM_BOT_TOKEN
    INPUT_CHAT_ID: $TELEGRAM_CHAT_ID
    INPUT_STATUS: success
    INPUT_NOTIFY_FIELDS: "actor,repository,workflow,branch,commit"
  script:
    - /actions-telegram-notifier
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"
      when: always

GitLab Merge Request Event

notify-mr:
  image: ghcr.io/prodreams/actions-telegram-notifier:latest
  variables:
    INPUT_TOKEN: $TELEGRAM_BOT_TOKEN
    INPUT_CHAT_ID: $TELEGRAM_CHAT_ID
    INPUT_STATUS: pending
    INPUT_NOTIFY_FIELDS: "actor,repository,workflow"
  script:
    - /actions-telegram-notifier
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: always

GitLab Tag Push

notify-tag:
  image: ghcr.io/prodreams/actions-telegram-notifier:latest
  variables:
    INPUT_TOKEN: $TELEGRAM_BOT_TOKEN
    INPUT_CHAT_ID: $TELEGRAM_CHAT_ID
    INPUT_STATUS: info
    INPUT_TITLE: "New tag released"
    INPUT_NOTIFY_FIELDS: "actor,repository"
  script:
    - /actions-telegram-notifier
  rules:
    - if: $CI_COMMIT_TAG
      when: always

Manual / Web / Schedule Trigger

notify-manual:
  image: ghcr.io/prodreams/actions-telegram-notifier:latest
  variables:
    INPUT_TOKEN: $TELEGRAM_BOT_TOKEN
    INPUT_CHAT_ID: $TELEGRAM_CHAT_ID
    INPUT_STATUS: info
    INPUT_NOTIFY_FIELDS: "actor,repository,workflow,branch"
    INPUT_MESSAGE: "Pipeline triggered from $CI_PIPELINE_SOURCE"
  script:
    - /actions-telegram-notifier
  rules:
    - if: $CI_PIPELINE_SOURCE == "web"
      when: always
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: always
    - if: $CI_PIPELINE_SOURCE == "api"
      when: always
    - if: $CI_PIPELINE_SOURCE == "trigger"
      when: always

For a complete example, see gitlab-ci.example.yml.

Notification Examples

Notification for Successful Workflow Completion in a Push Event

Notification for Opening a Pull Request

Notification for Closing a Pull Request

Notification for Merging a Pull Request

Notification for Workflow Dispatched

Author

• Ivan Ashikhmin

This Action was created as part of the "Code on a Napkin" project:

• Website: https://pressanybutton.ru/
• Telegram channel: https://t.me/napkincode

Support

If you like this project and would like to support its further development, please consider making a donation:

• Support via YooMoney
• Support via Tribute in Telegram
• Support via our Telegram bot

Contributors

License

This project is distributed under the MIT License. See the LICENSE file for details.