GitHub
En los flujos de trabajo CI/CD, eventos críticos como fallos de compilación, finalizaciones de despliegue y alertas de escaneo de seguridad a menudo necesitan comunicarse a los miembros del equipo de inmediato. Al integrar EngageLab SMS en GitHub Actions, puede activar notificaciones por SMS en cualquier punto de un Workflow, asegurando que los miembros del equipo estén informados del estado del sistema estén o no conectados.
Requisitos previos
Antes de comenzar, asegúrese de que las siguientes configuraciones estén completas:
Lado de EngageLab
- El servicio EngageLab SMS ha sido activado
- Se ha creado y aprobado una plantilla de SMS en la página de Gestión de Plantillas; se ha obtenido el ID de la plantilla
- Se ha creado una clave API en la página de Claves API; se han obtenido
dev_keyydev_secret
Lado de GitHub
- Tiene acceso de administrador al repositorio de destino y puede configurar Repository Secrets
Paso 1: Preparar plantillas de SMS
El envío de SMS a través de la API requiere plantillas preaprobadas; no se puede enviar contenido de texto personalizado directamente.
Inicie sesión en la consola de EngageLab, vaya a SMS → Gestión de Plantillas y cree una nueva plantilla. Para un ejemplo de notificación de despliegue, el contenido de la plantilla podría ser:
【{{sign}}】Hola, el repositorio {{repo}} {{status}} a las {{time}}, Commit: {{commit}}.
Después de enviar la plantilla, espere la aprobación y anote el ID de la plantilla (por ejemplo, deploy-notify-template).
Consejo: Cree plantillas separadas para "despliegue exitoso" y "despliegue fallido" — hace que la intención sea más clara y mejora la tasa de aprobación.
Paso 2: Configurar GitHub Secrets
Para evitar codificar secretos directamente en los archivos de Workflow, almacene la información sensible en GitHub Repository Secrets.
Vaya a la página de su repositorio, luego navegue a Settings → Secrets and variables → Actions → New repository secret, y agregue las siguientes variables una por una:
| Nombre del Secret | Descripción |
|---|---|
ENGAGELAB_DEV_KEY |
dev_key de la página de Claves API de EngageLab |
ENGAGELAB_DEV_SECRET |
dev_secret correspondiente |
ENGAGELAB_TEMPLATE_SUCCESS |
ID de plantilla para notificaciones de despliegue exitoso |
ENGAGELAB_TEMPLATE_FAILURE |
ID de plantilla para notificaciones de despliegue fallido |
ON_CALL_PHONE |
Número de teléfono para recibir notificaciones, debe incluir código de país, ej. +8618701235678 |
Paso 3: Agregar pasos de notificación al Workflow
La API de EngageLab SMS utiliza autenticación HTTP Basic, donde la cadena de autenticación se genera mediante base64(dev_key:dev_secret). A continuación se muestra un ejemplo completo de 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": "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')"'"
}
}
}'
Referencia de parámetros clave
| Parámetro | Descripción |
|---|---|
if: success() |
Se ejecuta solo cuando todos los pasos anteriores del Job actual tienen éxito |
if: failure() |
Se ejecuta solo cuando cualquier paso del Job actual falla |
github.repository |
Variable integrada de GitHub, con formato owner/repo |
github.sha |
El SHA del commit que activó este Workflow |
date '+%Y-%m-%d %H:%M' |
Obtiene la hora actual del Runner, por defecto en zona horaria UTC |
Nota: El comando
datedevuelve la hora del sistema del Runner de GitHub Actions (UTC). Para mostrar la zona horaria local, establezca la variable de entornoTZantes del comando, por ejemplo:TZ='Asia/Shanghai' date '+%Y-%m-%d %H:%M'.
Escenarios extendidos
Notificar a múltiples destinatarios
Cambie el campo to a un array para enviar a múltiples números de teléfono simultáneamente:
-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')"'"
}
}
}'
Alertas de escaneo de seguridad
En Workflows que incluyen pasos de escaneo de seguridad, envíe notificaciones inmediatas cuando se encuentren vulnerabilidades de alta gravedad:
- 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')"'"
}
}
}'
Informes de resultados de tareas programadas
Para Workflows activados por schedule (como sincronizaciones diarias de datos o copias de seguridad periódicas), envíe un SMS de resumen después de la ejecución:
on:
schedule:
- cron: '0 2 * * *' # Se ejecuta diariamente a las 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()significa que el paso se ejecuta independientemente de si los pasos anteriores tienen éxito o fallan — adecuado para escenarios donde las notificaciones siempre deben entregarse.
Notas importantes
- Las plantillas deben estar aprobadas antes de usarse. Si una plantilla está pendiente de revisión o ha sido rechazada al momento de llamarla, la API devolverá un error
4001. - Los números de teléfono deben incluir el código de país, por ejemplo, los números de China continental deben escribirse como
+8618701235678. Omitir+o el código de país causará un fallo en la entrega. - La cadena de autenticación se genera dinámicamente con cada solicitud — no es necesario almacenar el resultado codificado en Base64 de antemano. Simplemente calcúlelo en tiempo real usando
echo -n "key:secret" | base64. - Una respuesta HTTP 200 de la API no garantiza la entrega exitosa del SMS — verifique el campo
codeen el cuerpo de la respuesta. Uncodede0o ausente indica éxito; para valores distintos de cero, consulte la documentación de códigos de error para solucionar problemas. - Evite filtrar secretos en los registros — no haga
echodel contenido de la variableAUTHdirectamente en los pasosrun.
