Skip to content

README-RU.MD

Latest commit

 

History

History
262 lines (200 loc) · 13.8 KB

README-RU.MD

File metadata and controls

262 lines (200 loc) · 13.8 KB

Napkin Tools: Actions Telegram Notify

GitHub License GitHub Actions Workflow Status Код на салфетке Заметки на салфетке

Action для отправки уведомлений в Telegram о статусе выполнения Workflow на GitHub/Gitea/Github Actions совместимой CI/CD-системе.

Actions Telegram Notify помогает отслеживать статус выполняемых Workflow.

Оглавление

Особенности

  • Отправка обновлений о статусе в Telegram (например: успех, ошибка, отменено).
  • Настройка уведомлений с кастомизированным заголовком (title), сообщением (message) и подписью (footer).
  • Включение дополнительных полей в оповещение, таких как автор коммита, репозиторий, название Workflow и другие.
  • Поддерживает события Push, Pull Request, Pull Request Review и Workflow Dispatch. (Нужно больше? Откройте Issue или отправьте Pull Request!)
  • Автоматическое создание кнопки со ссылкой на Commit или Pull Request в уведомлении.

Требования

Для работы Actions Telegram Notify требуется:

  • Telegram Bot Token (его можно создать с помощью BotFather).
  • Telegram Chat ID:
    • Для личных сообщений от бота: 1234567.
    • Для небольшой группы: -1234567
    • Для большой группы/супергруппы: -1001234567
    • Важно:
      • Для личных сообщений необходимо начать диалог с ботом.
      • Для групп необходимо добавить бота в группу и дать ему минимальные права администратора, чтобы он смог отправлять сообщения.
  • (Необязательно) Telegram Chat Thread ID. Необходим для отправки сообщений в определённую тему в супергруппе.

Аргументы запуска

Название Обязательный Описание
token Да Telegram Bot Token. Используйте GitHub Secrets для безопасного хранения.
chat_id Да Telegram Chat ID. Используйте GitHub Secrets для безопасного хранения.
api_url Нет Пользовательский Bot API URL. Используйте GitHub Secrets для безопасного хранения.
thread_id Нет Telegram Chat Thread ID.
status Нет Статус рабочего процесса, получаем из ${{ job.status }}, либо передаем сами, например pending. По умолчанию info, если не указан.
title Нет Текст заголовка для сообщения. По умолчанию используется общее сообщение.
message Нет Пользовательский текст сообщения для включения в уведомление.
footer Нет Текст для добавления в конец уведомления.
notify_fields Нет Список дополнительных полей, разделенных запятыми, которые будут включены. Подробнее в Значения notify_fields
proxy_url Нет URL прокси-сервера для маршрутизации запросов (например, http://user:pass@127.0.0.1:8080 или socks5://ip:port).

Значения status

Статусы применимы для события Push.

Поле Описание
success Успешное выполнение Workflow.
failure Неуспешное выполнение Workflow.
cancelled Workflow отменён.
pending Workflow приостановлен.
info Информационный статус.

Значения notify_fields

Поле Событие Описание
actor Push, Pull Request, Pull Request Review, Workflow Dispatch Имя пользователя со ссылкой на профиль, запустившего Workflow.
repository Push, Pull Request, Pull Request Review, Workflow Dispatch Название репозитория со ссылкой, в котором выполняется Workflow.
workflow Push, Pull Request, Pull Request Review, Workflow Dispatch Название выполняемого Workflow.
branch Push Ветка, в которой запущен Workflow.
commit Push Первая строка сообщения коммита
repo_with_tag Push Название репозитория с тегом.

Пример использования

Событие Push

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"

Разбор полей

  • name - Указываем название шага (необязательно).
  • uses - Указываем используемый Action. Рекомендуется использовать актуальный из main-ветки.
  • if - Указываем условия запуска:
    • always() - Срабатывает всегда, при любом результате работы Workflow. (рекомендуется)
    • cancelled() - Срабатывает только при отменённом Workflow.
    • failure() - Срабатывает только при неуспешном выполнении Workflow.
    • success() - Срабатывает только при успешном Workflow.
  • with - перечень входных параметров, необходимых для работы. Подробнее в Аргументы запуска

Событие Pull Request

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

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

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"

Примеры уведомлений

Уведомление об успешном завершении Workflow в Push-событии

Success

Уведомлении об открытии Pull Request

PR Opened

Уведомлении о закрытии Pull Request

PR Opened

Уведомлении о слиянии Pull Request

PR Opened

Уведомление о ручном запуске Workflow

Workflow Dispatched

Автор

Action написан в рамках проекта "Код на салфетке":

Поддержка

Если вам нравится этот проект и вы хотите поддержать его дальнейшее развитие, рассмотрите возможность доната:

Участники

Участники

Лицензия

Этот проект распространяется под лицензией MIT. Подробности можно найти в файле LICENSE.