GitHub
In CI/CD-Abläufen müssen wichtige Ereignisse wie fehlgeschlagene Builds, abgeschlossene Deployments und Hinweise aus Sicherheitsscans oft sofort an die zuständigen Teammitglieder gehen. Durch die Einbindung von EngageLab SMS in GitHub Actions können Sie SMS-Benachrichtigungen an beliebiger Stelle im Workflow auslösen, sodass das Team den Systemstatus mitbekommt — online oder nicht.
Voraussetzungen
Bevor Sie starten, sollten folgende Konfigurationen abgeschlossen sein:
EngageLab-Seite
- Der EngageLab-SMS-Dienst ist aktiviert
- Eine SMS-Vorlage wurde auf der Seite „Vorlagenverwaltung“ erstellt und freigegeben; die Vorlagen-ID liegt vor
- Auf der Seite „API-Schlüssel“ wurde ein API-Schlüssel erstellt;
dev_keyunddev_secretliegen vor
GitHub-Seite
- Sie haben Administratorzugriff auf das Ziel-Repository und können Repository-Geheimnisse konfigurieren
Schritt 1: SMS-Vorlagen vorbereiten
Der Versand per API setzt freigegebene Vorlagen voraus; freier Fließtext kann nicht direkt versendet werden.
Melden Sie sich in der EngageLab-Konsole an, öffnen Sie SMS → Vorlagenverwaltung und legen Sie eine neue Vorlage an. Für eine Deployment-Benachrichtigung könnte der Vorlagentext etwa so aussehen:
【{{sign}}】Hello, repository {{repo}} {{status}} at {{time}}, Commit: {{commit}}.
Nach dem Einreichen warten Sie auf die Freigabe und notieren sich die Vorlagen-ID (z. B. deploy-notify-template).
Hinweis: Legen Sie getrennte Vorlagen für „Deployment erfolgreich“ und „Deployment fehlgeschlagen“ an — das macht die Absicht klarer und verbessert die Freigabequote.
Schritt 2: GitHub-Geheimnisse konfigurieren
Um keine Geheimnisse in Workflow-Dateien zu hinterlegen, speichern Sie sensible Daten in GitHub-Repository-Geheimnissen.
Öffnen Sie die Repository-Seite und navigieren Sie zu Einstellungen → Geheimnisse und Variablen → Actions → Neues Repository-Geheimnis, und fügen Sie nacheinander folgende Variablen hinzu:
| Geheimnisname | Beschreibung |
|---|---|
ENGAGELAB_DEV_KEY |
dev_key von der EngageLab-Seite „API-Schlüssel“ |
ENGAGELAB_DEV_SECRET |
Zugehöriges dev_secret |
ENGAGELAB_TEMPLATE_SUCCESS |
Vorlagen-ID für Benachrichtigungen bei erfolgreichem Deployment |
ENGAGELAB_TEMPLATE_FAILURE |
Vorlagen-ID für Benachrichtigungen bei fehlgeschlagenem Deployment |
ON_CALL_PHONE |
Empfangende Rufnummer, muss Landesvorwahl enthalten, z. B. +8618701235678 |
Schritt 3: Benachrichtigungsschritte im Workflow ergänzen
Die EngageLab-SMS-API nutzt HTTP-Basic-Authentifizierung; die Authentifizierungszeichenkette entsteht aus base64(dev_key:dev_secret). Nachfolgend ein vollständiges Workflow-Beispiel:
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": "deployed successfully",
"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 failed",
"time": "'"$(date '+%Y-%m-%d %H:%M')"'"
}
}
}'
Referenz zentraler Parameter
| Parameter | Beschreibung |
|---|---|
if: success() |
Wird nur ausgeführt, wenn alle vorherigen Schritte im aktuellen Job erfolgreich waren |
if: failure() |
Wird nur ausgeführt, wenn mindestens ein Schritt im aktuellen Job fehlgeschlagen ist |
github.repository |
Eingebaute GitHub-Variable im Format owner/repo |
github.sha |
Commit-SHA, die diesen Workflow ausgelöst hat |
date '+%Y-%m-%d %H:%M' |
Liefert die aktuelle Zeit auf dem Runner, standardmäßig in UTC |
Hinweis: Der Befehl
datenutzt die Systemzeit des GitHub-Actions-Runners (UTC). Für eine lokale Zeitzone setzen Sie vor dem Befehl die UmgebungsvariableTZ, z. B.:TZ='Asia/Shanghai' date '+%Y-%m-%d %H:%M'.
Erweiterte Szenarien
Mehrere Empfänger benachrichtigen
Ändern Sie das Feld to zu einem Array, um gleichzeitig an mehrere Rufnummern zu senden:
-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 failed",
"time": "'"$(date '+%Y-%m-%d %H:%M')"'"
}
}
}'
Hinweise aus Sicherheitsscans
In Workflows mit Sicherheitsscans können Sie bei kritischen Schwachstellen sofort SMS versenden:
- 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')"'"
}
}
}'
Berichte zu geplanten Aufgaben
Für Workflows mit Auslöser schedule (z. B. tägliche Datensynchronisation oder periodische Backups) können Sie nach der Ausführung eine kurze SMS zusammenfassen:
on:
schedule:
- cron: '0 2 * * *' # Runs daily at 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')"'"
}
}
}'
if: always()bedeutet, dass der Schritt unabhängig vom Erfolg oder Misserfolg vorheriger Schritte ausgeführt wird — geeignet, wenn Benachrichtigungen immer zugestellt werden sollen.
Wichtige Hinweise
- Vorlagen müssen vor der Nutzung freigegeben sein. Ist eine Vorlage in Prüfung oder abgelehnt, liefert die API einen
4001-Fehler. - Rufnummern müssen die Landesvorwahl enthalten, z. B. Festlandchina als
+8618701235678. Fehlt+oder die Landesvorwahl, schlägt die Zustellung fehl. - Die Authentifizierungszeichenkette wird bei jeder Anfrage neu erzeugt — ein vorab gespeicherter Base64-Wert ist nicht nötig. Berechnen Sie ihn zur Laufzeit mit
echo -n "key:secret" | base64. - Eine HTTP-200-Antwort der API garantiert keinen erfolgreichen SMS-Zustellweg — prüfen Sie das Feld
codeim Antworttext.0oder fehlend gilt als Erfolg; bei Werten ungleich null siehe die Dokumentation zu Fehlercodes. - Vermeiden Sie Geheimnis-Leaks in Logs — geben Sie den Inhalt der Variable
AUTHinrun-Schritten nicht perechoaus.
