Napkin Tools: Actions Telegram Notify

An action for sending notifications to Telegram about the status of a Workflow execution in a GitHub/Gitea/GitHub Actions-compatible CI/CD system.

Actions Telegram Notify helps track the status of running Workflows.

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

Table of Contents

• Features
• Requirements
• Execution Arguments
  • status Values
  • notify_fields Values
• Usage Example
  • Push Event
    • Field Breakdown
  • Pull Request Event
  • Workflow Dispatch Event
• 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 and Workflow Dispatch events. (Need more? Open an Issue or submit a Pull Request!)
• Automatically generates a button with a link to the Commit or Pull Request in the notification.

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 for secure storage.
chat_id	Yes	Telegram Chat ID. Use GitHub Secrets for secure storage.
api_url	No	Custom Telegram Bot API URL. Use GitHub 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:pass@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, Workflow Dispatch	Username with a profile link who triggered the Workflow.
repository	Push, Pull Request, Workflow Dispatch	Repository name with a link where the Workflow is running.
workflow	Push, Pull Request, 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.

Usage Example

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"

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"

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/press_any_button

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.