Github

Dalam alur CI/CD, event penting seperti build gagal, deployment selesai, dan peringatan pemindaian keamanan sering kali perlu segera diberitahukan kepada pihak terkait. Mengintegrasikan EngageLab SMS ke GitHub Actions memungkinkan Anda memicu notifikasi SMS di node mana pun dalam Workflow, memastikan anggota tim dapat segera mengetahui status sistem baik sedang online maupun tidak.

Prasyarat

Sebelum memulai, harap pastikan konfigurasi berikut sudah selesai:

Sisi EngageLab

Sudah mengaktifkan layanan EngageLab SMS
Sudah membuat template SMS di halaman pengelolaan template dan lolos peninjauan, serta mendapatkan ID template
Sudah membuat secret key API di halaman secret key API, serta mendapatkan dev_key dan dev_secret

Sisi GitHub

Memiliki hak akses admin pada repositori target, untuk mengonfigurasi Repository Secrets

Langkah Pertama: Menyiapkan Template SMS

Memanggil API untuk mengirim SMS harus menggunakan template yang sudah lolos peninjauan, tidak mendukung input teks kustom secara langsung.

Login ke konsol EngageLab, masuk ke SMS → Pengelolaan Template, lalu buat template baru. Sebagai contoh notifikasi deployment, konten template dapat dirancang sebagai:

【{{sign}}】Halo, repositori {{repo}} pada {{time}} {{status}}, Commit: {{commit}}.

              
              【{{sign}}】Halo, repositori {{repo}} pada {{time}} {{status}}, Commit: {{commit}}.

Tampilkan blok kode ini di jendela mengambang

Setelah template diajukan, tunggu hingga lolos peninjauan, lalu catat ID template (seperti deploy-notify-template).

Saran: Buat template terpisah untuk "deployment berhasil" dan "deployment gagal" agar maknanya lebih jelas dan tingkat kelulusan peninjauan lebih tinggi.

Langkah Kedua: Mengonfigurasi GitHub Secrets

Untuk menghindari hardcoding secret key ke dalam file Workflow, informasi sensitif perlu disimpan ke GitHub Repository Secrets.

Masuk ke halaman repositori, klik berurutan Settings → Secrets and variables → Actions → New repository secret, lalu tambahkan variabel berikut satu per satu:

Nama Secret	Penjelasan
`ENGAGELAB_DEV_KEY`	dev_key dari halaman secret key API EngageLab
`ENGAGELAB_DEV_SECRET`	dev_secret yang sesuai
`ENGAGELAB_TEMPLATE_SUCCESS`	ID template notifikasi deployment berhasil
`ENGAGELAB_TEMPLATE_FAILURE`	ID template notifikasi deployment gagal
`ON_CALL_PHONE`	Nomor ponsel penerima notifikasi, harus menyertakan kode negara, seperti `+6591234567`

Langkah Ketiga: Menambahkan Langkah Notifikasi di Workflow

EngageLab SMS API menggunakan HTTP Basic authentication, string autentikasi dihasilkan dari base64(dev_key:dev_secret). Berikut adalah contoh Workflow lengkap:

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": "deployment berhasil", "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": "deployment gagal", "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": "deployment berhasil",
                  "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": "deployment gagal",
                  "time": "'"$(date '+%Y-%m-%d %H:%M')"'"
                }
              }
            }'

Tampilkan blok kode ini di jendela mengambang

Penjelasan Parameter Penting

Parameter	Penjelasan
`if: success()`	Hanya dijalankan saat semua langkah sebelumnya pada Job ini berhasil
`if: failure()`	Hanya dijalankan saat ada langkah pada Job ini yang gagal
`github.repository`	Variabel bawaan GitHub, dengan format `owner/repo`
`github.sha`	Commit SHA yang memicu Workflow ini
`date '+%Y-%m-%d %H:%M'`	Mendapatkan waktu Runner saat ini, default zona waktu UTC

Catatan: Perintah date mendapatkan waktu sistem GitHub Actions Runner (UTC), jika perlu menampilkan waktu zona lokal, harap atur environment variable TZ sebelum perintah, misalnya: TZ='Asia/Shanghai' date '+%Y-%m-%d %H:%M'.

Skenario Lanjutan

Memberi Tahu Beberapa Penerima

Ubah field to menjadi array, agar dapat mengirim ke beberapa nomor ponsel sekaligus:

-d '{ "to": [ "${{ secrets.ON_CALL_PHONE }}", "${{ secrets.TEAM_LEAD_PHONE }}" ], "template": { "id": "${{ secrets.ENGAGELAB_TEMPLATE_FAILURE }}", "params": { "repo": "${{ github.repository }}", "commit": "${{ github.sha }}", "status": "deployment gagal", "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": "deployment gagal",
      "time": "'"$(date '+%Y-%m-%d %H:%M')"'"
    }
  }
}'

Tampilkan blok kode ini di jendela mengambang

Peringatan Pemindaian Keamanan

Pada Workflow yang berisi langkah pemindaian keamanan, segera beri tahu saat ditemukan kerentanan berisiko tinggi:

- 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')"'"
          }
        }
      }'

Tampilkan blok kode ini di jendela mengambang

Penyiaran Hasil Eksekusi Tugas Terjadwal

Untuk Workflow terjadwal yang dipicu melalui schedule (seperti sinkronisasi data harian, backup berkala), kirim SMS rangkuman setelah eksekusi selesai:

on: schedule: - cron: '0 2 * * *' # Dijalankan setiap hari pukul 02:00 UTC 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/Shanghai' date '+%Y-%m-%d %H:%M')"'" } } }'

              
              on:
  schedule:
    - cron: '0 2 * * *'   # Dijalankan setiap hari pukul 02:00 UTC

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/Shanghai' date '+%Y-%m-%d %H:%M')"'"
                }
              }
            }'

Tampilkan blok kode ini di jendela mengambang

if: always() berarti dijalankan baik langkah berhasil maupun gagal, cocok untuk skenario yang memerlukan jaminan notifikasi pasti terkirim.

Catatan Penting

Template harus lolos peninjauan sebelum dapat digunakan. Jika saat dipanggil template berstatus menunggu peninjauan atau ditolak, API akan mengembalikan error 4001.
Format nomor ponsel harus menyertakan kode negara, misalnya nomor Singapura harus ditulis +6591234567, tanpa + atau kode negara akan menyebabkan pengiriman gagal.
String autentikasi dihasilkan secara dinamis pada setiap request, tidak perlu menyimpan hasil encoding Base64 terlebih dahulu, cukup hitung secara real-time melalui echo -n "key:secret" | base64.
API mengembalikan HTTP 200 tidak berarti SMS berhasil dikirim, harap periksa field code pada response body, jika code bernilai 0 atau tidak ada berarti normal, jika tidak nol lihat penjelasan kode error untuk menyelidiki penyebabnya.
Hindari membocorkan secret key di log, jangan langsung echo isi variabel AUTH pada langkah run.