Github
En un flujo de CI/CD, eventos clave como un fallo de compilación, la finalización de un despliegue o una alerta de escaneo de seguridad suelen requerir notificar de inmediato a las personas implicadas. Al integrar EngageLab SMS en GitHub Actions, puedes disparar notificaciones por SMS en cualquier punto del Workflow, garantizando que los miembros del equipo perciban el estado del sistema a tiempo, estén o no conectados.
Requisitos previos
Antes de empezar, confirma que se ha completado la siguiente configuración:
En EngageLab
- Has activado el servicio EngageLab SMS
- Has creado una plantilla de SMS en la página de gestión de plantillas, ha sido aprobada y has obtenido el ID de la plantilla
- Has creado una API Key en la página de API Key y has obtenido el
dev_keyy eldev_secret
En GitHub
- Tienes permisos de administrador en el repositorio de destino, para poder configurar los Repository Secrets
Paso 1: prepara la plantilla de SMS
Para enviar SMS mediante la API es obligatorio usar plantillas previamente aprobadas; no se admite pasar texto personalizado directamente.
Inicia sesión en la consola de EngageLab, ve a SMS → Gestión de plantillas y crea una nueva plantilla. Tomando como ejemplo una notificación de despliegue, el contenido de la plantilla podría diseñarse así:
[{{sign}}] Hola, el repositorio {{repo}} {{status}} el {{time}}. Commit: {{commit}}.
Tras enviar la plantilla, espera a que sea aprobada y anota el ID de la plantilla (como deploy-notify-template).
Recomendación: crea plantillas independientes para «despliegue exitoso» y «despliegue fallido»; así la semántica es más clara y la tasa de aprobación es mayor.
Paso 2: configura los GitHub Secrets
Para evitar codificar las claves directamente en el archivo del Workflow, debes almacenar la información sensible en los Repository Secrets de GitHub.
Ve a la página del repositorio, haz clic sucesivamente en Settings → Secrets and variables → Actions → New repository secret y añade una a una las siguientes variables:
| Nombre del Secret | Descripción |
|---|---|
ENGAGELAB_DEV_KEY |
El dev_key de la página de API Key de EngageLab |
ENGAGELAB_DEV_SECRET |
El dev_secret correspondiente |
ENGAGELAB_TEMPLATE_SUCCESS |
El ID de la plantilla de notificación de despliegue exitoso |
ENGAGELAB_TEMPLATE_FAILURE |
El ID de la plantilla de notificación de despliegue fallido |
ON_CALL_PHONE |
El número de móvil que recibe la notificación, con código de país, como +6591234567 |
Paso 3: añade los pasos de notificación en el Workflow
La API de EngageLab SMS utiliza autenticación HTTP Basic, y 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": "se desplegó correctamente",
"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": "falló el despliegue",
"time": "'"$(date '+%Y-%m-%d %H:%M')"'"
}
}
}'
Descripción de los parámetros clave
| Parámetro | Descripción |
|---|---|
if: success() |
Se ejecuta solo si todos los pasos previos del Job actual fueron exitosos |
if: failure() |
Se ejecuta solo si algún paso del Job actual falló |
github.repository |
Variable integrada de GitHub, con el formato owner/repo |
github.sha |
El Commit SHA que disparó este Workflow |
date '+%Y-%m-%d %H:%M' |
Obtiene la hora actual del Runner; por defecto, en la zona horaria UTC |
Nota: el comando
dateobtiene la hora del sistema del Runner de GitHub Actions (UTC). Si necesitas mostrar la hora en la zona horaria local, define la variable de entornoTZantes del comando, por ejemplo:TZ='Asia/Shanghai' date '+%Y-%m-%d %H:%M'.
Escenarios ampliados
Notificar a varios destinatarios
Cambia el campo to por un array para enviar simultáneamente a varios números de móvil:
-d '{
"to": [
"${{ secrets.ON_CALL_PHONE }}",
"${{ secrets.TEAM_LEAD_PHONE }}"
],
"template": {
"id": "${{ secrets.ENGAGELAB_TEMPLATE_FAILURE }}",
"params": {
"repo": "${{ github.repository }}",
"commit": "${{ github.sha }}",
"status": "falló el despliegue",
"time": "'"$(date '+%Y-%m-%d %H:%M')"'"
}
}
}'
Alerta de escaneo de seguridad
En un Workflow que incluya pasos de escaneo de seguridad, notifica de inmediato cuando se detecte una vulnerabilidad de alto riesgo:
- 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')"'"
}
}
}'
Difusión del resultado de las tareas programadas
Para los Workflows programados que se disparan mediante schedule (como la sincronización diaria de datos o las copias de seguridad periódicas), envía un SMS de resumen al finalizar la ejecución:
on:
schedule:
- cron: '0 2 * * *' # Se ejecuta cada día 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()indica que se ejecuta tanto si los pasos tienen éxito como si fallan; es adecuado para escenarios en los que hay que garantizar que la notificación llegue siempre.
Consideraciones
- La plantilla solo puede usarse después de ser aprobada. Si al llamar la plantilla está pendiente de revisión o ha sido rechazada, la API devolverá el error
4001. - El formato del número de móvil debe incluir el código de país; por ejemplo, un número de Singapur debe escribirse como
+6591234567. Si falta el+o el código de país, el envío fallará. - La cadena de autenticación se genera dinámicamente en cada solicitud: no es necesario almacenar de antemano el resultado codificado en Base64; basta con calcularlo en tiempo real mediante
echo -n "key:secret" | base64. - Que la API devuelva HTTP 200 no significa que el SMS se haya enviado con éxito; comprueba el campo
codeen el cuerpo de la respuesta. Sicodees0o no existe, indica que todo es correcto; si no es cero, consulta la descripción de los códigos de error para investigar la causa. - Evita exponer las claves en los logs: no hagas
echodirectamente del contenido de la variableAUTHen los pasosrun.
