Github

在 CI/CD 流程中，建置失敗、部署完成、安全掃描警報等關鍵事件往往需要第一時間通知到相關人員。將 EngageLab SMS 整合到 GitHub Actions，可以在 Workflow 的任意節點觸發簡訊通知，確保團隊成員無論是否線上都能及時感知系統狀態。

前置條件

開始前，請確認以下設定已完成：

EngageLab 側

已開通 EngageLab SMS 服務
已在範本管理頁面建立簡訊範本並通過審核，取得範本 ID
已在 API 金鑰頁面建立 API 金鑰，取得 dev_key 和 dev_secret

GitHub 側

擁有目標儲存庫的管理員權限，可設定 Repository Secrets

第一步：準備簡訊範本

呼叫 API 發送簡訊必須使用預先審核通過的範本，不支援直接傳入自訂文字。

登入 EngageLab 控制台，進入 SMS → 範本管理，新增範本。以部署通知為例，範本內容可設計為：

【{{sign}}】您好，儲存庫 {{repo}} 於 {{time}} {{status}}，Commit：{{commit}}。

              
              【{{sign}}】您好，儲存庫 {{repo}} 於 {{time}} {{status}}，Commit：{{commit}}。

此代碼塊在浮窗中顯示

範本提交後等待審核通過，記錄範本 ID（如 deploy-notify-template）。

建議：為「部署成功」和「部署失敗」分別建立獨立範本，語意更清晰，審核通過率也更高。

第二步：設定 GitHub Secrets

為避免將金鑰硬編碼到 Workflow 檔案中，需將敏感資訊儲存到 GitHub Repository Secrets。

進入儲存庫頁面，依序點擊 Settings → Secrets and variables → Actions → New repository secret，逐一新增以下變數：

Secret 名稱	說明
`ENGAGELAB_DEV_KEY`	EngageLab API 金鑰頁面的 dev_key
`ENGAGELAB_DEV_SECRET`	對應的 dev_secret
`ENGAGELAB_TEMPLATE_SUCCESS`	部署成功通知的範本 ID
`ENGAGELAB_TEMPLATE_FAILURE`	部署失敗通知的範本 ID
`ON_CALL_PHONE`	接收通知的手機號碼，需含國家代碼，如 `+6591234567`

第三步：在 Workflow 中新增通知步驟

EngageLab SMS API 採用 HTTP Basic 認證，授權字串由 base64(dev_key:dev_secret) 產生。以下為完整的 Workflow 範例：

name: Deploy to Production on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Build and test run: | npm install npm test - name: Deploy run: ./deploy.sh - name: Notify success via EngageLab SMS if: success() run: | AUTH=$(echo -n "${{ secrets.ENGAGELAB_DEV_KEY }}:${{ secrets.ENGAGELAB_DEV_SECRET }}" | base64) curl -s -X POST https://smsapi.engagelab.com/v1/messages \ -H "Content-Type: application/json" \ -H "Authorization: Basic ${AUTH}" \ -d '{ "to": ["${{ secrets.ON_CALL_PHONE }}"], "template": { "id": "${{ secrets.ENGAGELAB_TEMPLATE_SUCCESS }}", "params": { "repo": "${{ github.repository }}", "commit": "${{ github.sha }}", "status": "部署成功", "time": "'"$(date '+%Y-%m-%d %H:%M')"'" } } }' - name: Notify failure via EngageLab SMS if: failure() run: | AUTH=$(echo -n "${{ secrets.ENGAGELAB_DEV_KEY }}:${{ secrets.ENGAGELAB_DEV_SECRET }}" | base64) curl -s -X POST https://smsapi.engagelab.com/v1/messages \ -H "Content-Type: application/json" \ -H "Authorization: Basic ${AUTH}" \ -d '{ "to": ["${{ secrets.ON_CALL_PHONE }}"], "template": { "id": "${{ secrets.ENGAGELAB_TEMPLATE_FAILURE }}", "params": { "repo": "${{ github.repository }}", "commit": "${{ github.sha }}", "status": "部署失敗", "time": "'"$(date '+%Y-%m-%d %H:%M')"'" } } }'

              
              name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Build and test
        run: |
          npm install
          npm test

      - name: Deploy
        run: ./deploy.sh

      - name: Notify success via EngageLab SMS
        if: success()
        run: |
          AUTH=$(echo -n "${{ secrets.ENGAGELAB_DEV_KEY }}:${{ secrets.ENGAGELAB_DEV_SECRET }}" | base64)
          curl -s -X POST https://smsapi.engagelab.com/v1/messages \
            -H "Content-Type: application/json" \
            -H "Authorization: Basic ${AUTH}" \
            -d '{
              "to": ["${{ secrets.ON_CALL_PHONE }}"],
              "template": {
                "id": "${{ secrets.ENGAGELAB_TEMPLATE_SUCCESS }}",
                "params": {
                  "repo": "${{ github.repository }}",
                  "commit": "${{ github.sha }}",
                  "status": "部署成功",
                  "time": "'"$(date '+%Y-%m-%d %H:%M')"'"
                }
              }
            }'

      - name: Notify failure via EngageLab SMS
        if: failure()
        run: |
          AUTH=$(echo -n "${{ secrets.ENGAGELAB_DEV_KEY }}:${{ secrets.ENGAGELAB_DEV_SECRET }}" | base64)
          curl -s -X POST https://smsapi.engagelab.com/v1/messages \
            -H "Content-Type: application/json" \
            -H "Authorization: Basic ${AUTH}" \
            -d '{
              "to": ["${{ secrets.ON_CALL_PHONE }}"],
              "template": {
                "id": "${{ secrets.ENGAGELAB_TEMPLATE_FAILURE }}",
                "params": {
                  "repo": "${{ github.repository }}",
                  "commit": "${{ github.sha }}",
                  "status": "部署失敗",
                  "time": "'"$(date '+%Y-%m-%d %H:%M')"'"
                }
              }
            }'

此代碼塊在浮窗中顯示

關鍵參數說明

參數	說明
`if: success()`	僅在目前 Job 所有前置步驟均成功時執行
`if: failure()`	僅在目前 Job 任意步驟失敗時執行
`github.repository`	GitHub 內建變數，格式為 `owner/repo`
`github.sha`	觸發本次 Workflow 的 Commit SHA
`date '+%Y-%m-%d %H:%M'`	取得 Runner 目前時間，預設為 UTC 時區

注意：date 命令取得的是 GitHub Actions Runner 的系統時間（UTC），若需要顯示本地時區時間，請在命令前設定 TZ 環境變數，例如：TZ='Asia/Taipei' date '+%Y-%m-%d %H:%M'。

擴充場景

通知多位接收人

將 to 欄位改為陣列，可同時向多個手機號碼發送：

-d '{ "to": [ "${{ secrets.ON_CALL_PHONE }}", "${{ secrets.TEAM_LEAD_PHONE }}" ], "template": { "id": "${{ secrets.ENGAGELAB_TEMPLATE_FAILURE }}", "params": { "repo": "${{ github.repository }}", "commit": "${{ github.sha }}", "status": "部署失敗", "time": "'"$(date '+%Y-%m-%d %H:%M')"'" } } }'

              
              -d '{
  "to": [
    "${{ secrets.ON_CALL_PHONE }}",
    "${{ secrets.TEAM_LEAD_PHONE }}"
  ],
  "template": {
    "id": "${{ secrets.ENGAGELAB_TEMPLATE_FAILURE }}",
    "params": {
      "repo": "${{ github.repository }}",
      "commit": "${{ github.sha }}",
      "status": "部署失敗",
      "time": "'"$(date '+%Y-%m-%d %H:%M')"'"
    }
  }
}'

此代碼塊在浮窗中顯示

安全掃描警報

在包含安全掃描步驟的 Workflow 中，發現高危漏洞時立即通知：

- name: Security scan id: security run: ./run-security-scan.sh - name: Notify security alert via SMS if: steps.security.outputs.high_severity == 'true' run: | AUTH=$(echo -n "${{ secrets.ENGAGELAB_DEV_KEY }}:${{ secrets.ENGAGELAB_DEV_SECRET }}" | base64) curl -s -X POST https://smsapi.engagelab.com/v1/messages \ -H "Content-Type: application/json" \ -H "Authorization: Basic ${AUTH}" \ -d '{ "to": ["${{ secrets.SECURITY_TEAM_PHONE }}"], "template": { "id": "${{ secrets.ENGAGELAB_TEMPLATE_SECURITY }}", "params": { "repo": "${{ github.repository }}", "time": "'"$(date '+%Y-%m-%d %H:%M')"'" } } }'

              
              - name: Security scan
  id: security
  run: ./run-security-scan.sh

- name: Notify security alert via SMS
  if: steps.security.outputs.high_severity == 'true'
  run: |
    AUTH=$(echo -n "${{ secrets.ENGAGELAB_DEV_KEY }}:${{ secrets.ENGAGELAB_DEV_SECRET }}" | base64)
    curl -s -X POST https://smsapi.engagelab.com/v1/messages \
      -H "Content-Type: application/json" \
      -H "Authorization: Basic ${AUTH}" \
      -d '{
        "to": ["${{ secrets.SECURITY_TEAM_PHONE }}"],
        "template": {
          "id": "${{ secrets.ENGAGELAB_TEMPLATE_SECURITY }}",
          "params": {
            "repo": "${{ github.repository }}",
            "time": "'"$(date '+%Y-%m-%d %H:%M')"'"
          }
        }
      }'

此代碼塊在浮窗中顯示

排程任務執行結果播報

對於透過 schedule 觸發的排程 Workflow（如每日資料同步、定期備份），執行完成後發送彙總簡訊：

on: schedule: - cron: '0 2 * * *' # 每天 UTC 02:00 執行 jobs: daily-sync: runs-on: ubuntu-latest steps: - name: Run daily sync run: ./daily-sync.sh - name: Notify result via SMS if: always() run: | STATUS=${{ job.status }} AUTH=$(echo -n "${{ secrets.ENGAGELAB_DEV_KEY }}:${{ secrets.ENGAGELAB_DEV_SECRET }}" | base64) curl -s -X POST https://smsapi.engagelab.com/v1/messages \ -H "Content-Type: application/json" \ -H "Authorization: Basic ${AUTH}" \ -d '{ "to": ["${{ secrets.ON_CALL_PHONE }}"], "template": { "id": "${{ secrets.ENGAGELAB_TEMPLATE_DAILY }}", "params": { "repo": "${{ github.repository }}", "status": "'"${STATUS}"'", "time": "'"$(TZ='Asia/Taipei' date '+%Y-%m-%d %H:%M')"'" } } }'

              
              on:
  schedule:
    - cron: '0 2 * * *'   # 每天 UTC 02:00 執行

jobs:
  daily-sync:
    runs-on: ubuntu-latest
    steps:
      - name: Run daily sync
        run: ./daily-sync.sh

      - name: Notify result via SMS
        if: always()
        run: |
          STATUS=${{ job.status }}
          AUTH=$(echo -n "${{ secrets.ENGAGELAB_DEV_KEY }}:${{ secrets.ENGAGELAB_DEV_SECRET }}" | base64)
          curl -s -X POST https://smsapi.engagelab.com/v1/messages \
            -H "Content-Type: application/json" \
            -H "Authorization: Basic ${AUTH}" \
            -d '{
              "to": ["${{ secrets.ON_CALL_PHONE }}"],
              "template": {
                "id": "${{ secrets.ENGAGELAB_TEMPLATE_DAILY }}",
                "params": {
                  "repo": "${{ github.repository }}",
                  "status": "'"${STATUS}"'",
                  "time": "'"$(TZ='Asia/Taipei' date '+%Y-%m-%d %H:%M')"'"
                }
              }
            }'

此代碼塊在浮窗中顯示

if: always() 表示無論步驟成功或失敗均執行，適合需要保證通知必達的場景。

注意事項

範本必須審核通過後方可使用。呼叫時若範本處於待審核或審核拒絕狀態，API 將回傳 4001 錯誤。
手機號碼格式需含國家代碼，如新加坡號碼應寫為 +6591234567，不含 + 或國家代碼會導致發送失敗。
授權字串在每次請求時動態產生，無需提前儲存 Base64 編碼後的結果，直接透過 echo -n "key:secret" | base64 即時計算即可。
API 回傳 HTTP 200 並不代表簡訊發送成功，請檢查回應本體中的 code 欄位，code 為 0 或不存在時表示正常，非零時參考錯誤碼說明排查原因。
避免在日誌中洩露金鑰，不要在 run 步驟中直接 echo 輸出 AUTH 變數內容。