Alertas de fallos de GitHub Actions en tu iPhone

GitHub ya te avisa de las ejecuciones de tus flujos de trabajo: en la app GitHub Mobile, activa las notificaciones de Actions y recibirás una notificación por cada ejecución que hayas lanzado tú. Si no necesitas más, no hace falta seguir.

Honk sirve cuando necesitas más: los fallos de muchos repositorios, también los de ejecuciones que lanzaron otras personas, reunidos en un grupo por flujo de trabajo y rama, en la misma bandeja de entrada que tus servidores y tus tareas cron, y una recuperación cuando la rama vuelve a verde. La forma más rápida es conectar el webhook de GitHub con Honk: una URL, sin cambiar nada en tus flujos de trabajo. Si prefieres decidirlo en el propio flujo, la segunda mitad de esta guía añade un paso al final de un trabajo.

Antes de empezar

• Una cuenta de Honk. De momento, por invitación: solicita acceso.
• Un proyecto para la CI, en un espacio de trabajo en el que seas propietario o administrador.
• Acceso de administrador al repositorio, o a la organización, en GitHub.

1. Conecta GitHub en Honk

En la app web de Honk, abre el proyecto, entra en Conexiones y haz clic en Conectar un servicio. Elige GitHub y haz clic en Conectar. Honk muestra la URL del webhook de la conexión, que empieza por https://honk-honk.app/v1/hooks/github/.

En Secreto de firma, haz clic en Generar, copia el secreto y haz clic en Guardar secreto. GitHub firma cada entrega con él, y Honk rechaza las que no coinciden. Una vez guardado, Honk no vuelve a mostrar el secreto.

2. Añade el webhook en GitHub

En el repositorio, abre Settings ▸ Webhooks y haz clic en Add webhook. Para cubrir todos los repositorios a la vez, usa Settings ▸ Webhooks de la organización. Después, rellena:

• Payload URL: la URL de Honk.
• Content type: application/json. Honk no puede leer la codificación de formulario que GitHub usa por defecto.
• Secret: el secreto que generaste.
• Which events would you like to trigger this webhook?: elige Let me select individual events y marca Workflow runs, y también Deployment statuses, Releases e Issues si los quieres.

Haz clic en Add webhook. GitHub envía un ping al momento, y la conexión en Honk lo muestra como su última entrega.

3. Revisa las entregas

La pestaña Recent Deliveries del webhook en GitHub muestra cada entrega con la respuesta de Honk: 202 cuando Honk la aceptó, también si es un tipo de evento que ignora, y 401 cuando la firma no coincide. En Honk, la conexión muestra la hora de la última entrega, o el último error.

La próxima ejecución que falle en cualquier rama te avisará. No hace falta nada más: ni secretos en el repositorio ni pasos que añadir, y cubre todos los flujos de trabajo, también los nuevos.

Qué genera cada evento

• Una ejecución fallida (workflow_run), también una que no llegó a arrancar o que superó el tiempo límite: un problema, un Bocinazo largo con el título «CI failed on main · acme/api» (Honk escribe estos títulos en inglés), con el número de ejecución, quién la lanzó, el mensaje del commit y un enlace a la ejecución. Un grupo por repositorio, flujo de trabajo y rama.
• La siguiente ejecución correcta en esa rama: una recuperación, «CI passed on main · acme/api», que cierra el problema. Un éxito sin un fallo previo se descarta, así que una rama sana nunca te molesta. Las ejecuciones canceladas u omitidas se ignoran.
• Un despliegue fallido (deployment_status): un problema, un Bocinazo largo, un grupo por repositorio y entorno. El siguiente despliegue correcto lo cierra, y uno correcto sin un fallo previo es un Bip-bip, «Deployed to production · acme/api».
• Una versión publicada (release): un Bocinazo suave, con las notas de la versión.
• Una issue recién abierta (issues): un Bocinazo suave, un grupo por issue.

En Eventos que se convierten en mensajes, en la conexión, desmarca los que no quieras y haz clic en Guardar. Cada conexión cuenta para el plan de tu espacio de trabajo: Free incluye 2, Pro 20 y Team 100. Los mensajes cuentan para los límites diarios del plan, como cualquier otro; los encontrarás en precios.

O bien: un paso en el flujo de trabajo

Sin la conexión, un paso al final de un trabajo puede notificar el fallo por sí mismo. Así eliges en cada trabajo qué enviar, y funciona donde no puedes añadir un webhook. Usa una vía o la otra para los mismos flujos de trabajo: con las dos, te enterarías de cada fallo dos veces.

Esta vía necesita una clave de ingesta: en la app web, abre el proyecto, entra en Claves y crea una.

Guarda la URL y la clave como secretos

Los secretos de repositorio sirven para un solo repositorio; los de organización te ahorran repetir esto en todas partes. Con la CLI de GitHub:

# with the GitHub CLI, for one repository (or use --org for all of them)
gh secret set HONK_URL --body "https://honk-honk.app"
gh secret set HONK_KEY        # paste the ingestion key when asked

Añade un paso que solo se ejecute si algo falla

Pon este paso al final del trabajo que te interesa. if: failure() hace que solo se ejecute cuando ha fallado un paso anterior. Usa jq y curl, que ya están en todos los runners alojados en GitHub, así que no hay que instalar nada:

      - name: Tell Honk
        if: failure()
        env:
          HONK_URL: ${{ secrets.HONK_URL }}
          HONK_KEY: ${{ secrets.HONK_KEY }}
          WORKFLOW: ${{ github.workflow }}
          REPO: ${{ github.repository }}
          BRANCH: ${{ github.ref_name }}
          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
          ATTEMPT: ${{ github.run_id }}-${{ github.run_attempt }}
        run: |
          jq -n --arg title "CI failed: $WORKFLOW on $BRANCH" --arg url "$RUN_URL" --arg key "ci/$REPO/$BRANCH" \
            '{title: $title, message: $url, url: $url, severity: "long", event_type: "problem",
              group_key: $key, source: "github-actions", category: "deployments"}' |
          curl -sS --max-time 10 --retry 3 --retry-all-errors "$HONK_URL/v1/messages" \
            -H "Authorization: Bearer $HONK_KEY" -H "Content-Type: application/json" \
            -H "Idempotency-Key: gh-$ATTEMPT" --data-binary @- || true

Hay varios detalles que importan:

• La clave de grupo es el repositorio más la rama, ci/acme/api/main. El primer fallo en main te avisa al momento; los siguientes fallos en main se suman al mismo grupo como actualizaciones discretas. Un fallo en otra rama forma su propio grupo.
• La clave de idempotencia es el id de la ejecución más el intento. Si curl reintenta porque se perdió una respuesta, Honk devuelve el evento original en vez de crear otro; en cambio, si pulsas Re-run, el nuevo intento es un evento nuevo.
• jq construye el JSON, así que un nombre de flujo de trabajo o de rama con comillas no puede romper la solicitud.
• || true evita que una caída de Honk convierta una compilación fallida en un fallo distinto.

Opcional: una recuperación cuando vuelva a verde

Para cerrar la incidencia cuando la rama vuelva a pasar, añade un segundo paso que se ejecute si todo va bien, pregunte a GitHub si falló la ejecución anterior en esa rama y solo entonces notifique una recuperación:

      # needs `permissions: actions: read` when the workflow restricts the token
      - name: Tell Honk it works again
        if: success()
        env:
          GH_TOKEN: ${{ github.token }}
          HONK_URL: ${{ secrets.HONK_URL }}
          HONK_KEY: ${{ secrets.HONK_KEY }}
          WORKFLOW: ${{ github.workflow }}
          REPO: ${{ github.repository }}
          BRANCH: ${{ github.ref_name }}
          ATTEMPT: ${{ github.run_id }}-${{ github.run_attempt }}
        run: |
          previous=$(gh run list --repo "$REPO" --workflow "$WORKFLOW" --branch "$BRANCH" \
            --limit 2 --json conclusion --jq '.[1].conclusion')
          [ "$previous" = "failure" ] || exit 0
          jq -n --arg title "CI green again: $WORKFLOW on $BRANCH" --arg key "ci/$REPO/$BRANCH" \
            '{title: $title, message: "The last run passed.", severity: "beep", event_type: "recovery",
              group_key: $key, source: "github-actions", category: "deployments"}' |
          curl -sS --max-time 10 --retry 3 --retry-all-errors "$HONK_URL/v1/messages" \
            -H "Authorization: Bearer $HONK_KEY" -H "Content-Type: application/json" \
            -H "Idempotency-Key: gh-$ATTEMPT-ok" --data-binary @- || true

Sin este paso no se rompe nada: un episodio sin eventos nuevos queda inactivo a las 24 horas, y el siguiente fallo abre uno nuevo y vuelve a avisar.

Lo mismo con la CLI honk

Si prefieres la CLI honk, que reintenta por ti con una misma clave de idempotencia y un tiempo límite total, instálala en los pasos que se ejecutan cuando el trabajo falla y llama a uhoh. Go viene preinstalado en los runners Linux alojados en GitHub:

      - name: Install the honk CLI
        if: failure()
        run: |
          go install github.com/honk-hq/go/cmd/honk@latest
          echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"

      - name: Notify
        if: failure()
        env:
          HONK_URL: ${{ secrets.HONK_URL }}
          HONK_KEY: ${{ secrets.HONK_KEY }}
        run: |
          honk uhoh --group-key "ci/${{ github.repository }}/${{ github.ref_name }}" \
            --title "CI failed: ${{ github.workflow }}" --message "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
            --source github-actions --category deployments \
            --idempotency-key "gh-${{ github.run_id }}-${{ github.run_attempt }}" || true

Qué consigues

El primer fallo de main llega a Honk para iPhone como Bocinazo largo, y en la bandeja de entrada tienes el enlace a la ejecución. Las repeticiones en la misma rama actualizan un único grupo en lugar de hacer vibrar otra vez el teléfono, y las horas de silencio retienen los fallos de CI por la noche, salvo que sean urgentes. Para avisar también de los despliegues correctos, consulta la guía de despliegues, y la guía de Sentry añade los errores que lanza tu app una vez en producción.