---
title: 使用自己的 Telegram Bot 來接收 GitHub 通知
tags: Telegram, GitHub, Bot
---
# 筆記：使用自己的 Telegram Bot 來接收 GitHub 的 Event Integration

## 前言
Telegram 上本來就有些公開的 Bot 供大家使用，通常是加入 Bot 好友後會獲得一組 WebHook，輸入專案並設定要通知的項目就可以使用。
既然如此，為什麼要自己弄一隻 Bot 呢？比較明顯的理由之一就是，非官方提供的服務的信任度，畢竟牽扯到原始碼的通知可能會有一些你不想讓別人看到的東西(即使 GitHub 上的東西大多數是公開的)；之二則是自己來能夠有一些更彈性的地方，比如說客製化的通知內容。當然你也可以像我一樣，就是單純很想自己動手做做看（笑）。

## 參考資料

> Telegram Bot API : [Doc](https://core.telegram.org/bots/api)
> GitHub Action : [Doc](https://docs.github.com/en/actions)
> [appleboy/telegram-action](https://github.com/appleboy/telegram-action)

## 需求
1. Telegram 帳號
2. GitHub 帳號
:::info
不需要準備伺服器或域名，是我覺得讓這件事的門檻大大降低的要素之一。 :smiley:
:::

## 設定流程

### 準備 Telegram Bot
1. 在 Telegram 搜尋 BotFather([@botFather](https://t.me/botFather)) 並加入好友。
2. 在對話框中輸入 `/start` 啟動與 BotFather 的對話，然後輸入`/newbot` 來啟動產生一個自己的 bot 的流程，接下來會在互動中讓你輸入以下資訊：
- Bot 的名稱，可以是隨意的字串。之後可以再變更。
- Bot 的 username，英數底線，必須以 bot 結尾。
:::info
在產生完 bot 之後，可以在跟 BotFather 的對話中輸入 `/mybots` 來確認自己有幾個 bot，也可以在這邊編輯 bot 的詳細資訊及更換 bot 的頭像。
更換 bot 頭像的時候，不能以檔案形式傳送圖片，一定要用傳照片的方法。
:::
3. 產生完 Bot 後，BotFather 會告訴你加入 Bot 好友的連結（當然你也可以用自己剛剛設定的 username 把 Bot 加入好友）以及這個 Bot 的 Token。
:::info
請小心保管這組 Token，因為任何人都可以用這組 Token 透過 API 來控制你的 Bot。
:::
4. 在你與你的 Bot 的對話框，或你把 Bot 加入、打算用來接收通知的群組發一個任意的訊息。
:::info
如果你沒有發這個訊息，下一步就會找不到 id！
:::
5. 使用以下的指令來獲得聊天室的 ID：

    curl https://api.telegram.org/bot${TOKEN}/getUpdates

:::info
請注意在域名後面的字串，必須先接`bot`三個字，後面緊跟自己的 TOKEN！
:::
應該會獲得以下結構的回應，需要記住的部分為`result.message.from.id`：

    {
        "ok":true,
        "result": [
            {
                "update_id":數字,
                "message": {
                    "message_id":數字,
                    "from": {
                        "id":數字,
                        "is_bot":布林,
                        "first_name":你設定的名字,
                        "last_name":你設定的姓氏,
                        "username":你自己的 username,
                        "language_code":你使用的語言設定
                    },
                    "chat": {
                        "id":跟上面的 from.id 一樣的數字,
                        "first_name":同 from,
                        "last_name":同 from,
                        "username":同 from,
                        "type":"private"},
                    "date":數字格式的日期資料,
                    "text":你發送的內容
                }
            }
        ]
    }

若你得到的 `ok` 為 ` false`，可能是 TOKEN 前面忘了加 bot 導致沒有正確查到你的 bot，或是你還沒有發訊息給 bot ，查不到你們的對話內容。

### GitHub 設定
1. 打開你想要設定通知的 repository 的頁面，打開 `Settings` -> `Security/Secrets` -> `Actions`。
2. 按下右上角的 `New repository secret`，在 `Name` 的地方輸入變數名稱、`Value` 的地方輸入剛剛取得的 Token 及 ID。以下假設變數名稱分別為 `TOKEN` 跟 `ID`

### Action YML 檔案設定
1. 在你的 repository 的根目錄新增以下的目錄： `/.github/workflows/`。
:::info
小心不要漏掉 `workflows` 最後面的 s！
:::
2. 在 `/.github/workflows/` 裡面新增一個 `.yml` 檔。
:::info
檔名沒有一定要取什麼，目前我測試用不同英文字串當檔名都讀得到。
一個 repository 的 `/.github/workflows/` 中可以有複數個 `.yml` 檔，並且都會被套用。
:::
3. 在檔案中輸入以下內容（可根據自己的需要改寫）：

    # 幫這個 action 取個名字，會在 action 頁面的左側顯示
    name: Telegram Notification Push
    
    # 要在什麼時候觸發，實測只設定 push 沒有限定更細的 type 或條件時，
    # 新增 tag、設定 release 等活動都會觸發
    on:
      push
    
    # 設定 job 的內容
    jobs:

      bulid:
        # 被觸發後，點進上面的名稱後，這邊的名稱會顯示在流程頁面中
        name: Build
        # action 執行的環境
        runs-on: ubuntu-latest
        steps:
        # 再點入上面的流程看詳細執行狀況時，會顯示下面的名字
        - name: send message on push
          # 使用這個專案已經寫好的 action
          uses: appleboy/telegram-action@master
          with:
            # 將剛剛拿到的參數帶入，讓流程能夠正確將訊息發到指定的聊天室
            to: ${{ secrets.ID }}
            token: ${{ secrets.TOKEN }}
            # 設定要發出的訊息格式，以下是參考原始 repo 後稍微改寫的設定
            # github.actor: 觸發 event 的使用者名稱
            # github.sha: commit 的 hash 值
            # github.event.commits[0].message: commit message
            # github.repository: repository 的名稱
            message: |
               ${{ github.actor }} created commit: 
               Commit message: ${{ github.event.commits[0].message }}
               Repository: ${{ github.repository }}

               https://github.com/${{ github.repository }}/commit/${{github.sha}}

4. 將以上檔案 `git add` 加入 repository，commit 後 `git push` 到 GitHub。如果 `/.github/workflows/*.yml` 存在，且被觸發（比如設定了 `on: push` 之後 push 了），就可以在 repository 的 `Action` 頁面查看執行狀況。若是正確執行，會顯示執行的流程及時間；若有任何錯誤導致執行失敗，也會顯示一些錯誤訊息。

#### 關於 Workflow 中的輸入輸出
最近 GitHub Action 更新了輸出的方式，要將 run 過的參數傳給下個 step ，用以下的方法來設定輸出的 name 跟 value：

# 單行時的輸出
echo "name=value" >> $GITHUB_OUTPUT
# 複數行的輸出
echo "name<<EOF" >> $GITHUB_OUTPUT
echo "line1"
echo "line2"
echo "EOF" >> $GITHUB_OUTPUT