Documentación / Integraciones / GitHub Action

GitHub Action

Ejecuta kedgeway en cada pull request y haz fallar el build cuando un hallazgo alcance tu umbral, o ejecútalo de forma programada y deja que abra el pull request de migración.

Inicio rápido

kedgeway init

Esto escribe .github/workflows/kedgeway.yml, fijado a la versión instalada. Después agrega el secreto: ejecuta kedgeway login --export y guarda su salida como un secreto del repositorio llamado KEDGEWAY_AUTH. Usa --print para ver el YAML antes de escribirlo y --force para sobrescribir un archivo existente. Consulta Comandos.

Úsala

- uses: actions/checkout@v4
- uses: Klorenn/kedgeway@v0.1.0
  with:
    path: .
    fail-on: warning
    auth: ${{ secrets.KEDGEWAY_AUTH }}   # live Raven data; or use fixture: for offline

Fija un tag de release como en el ejemplo. @main no está fijado y puede cambiar sin aviso.

Entradas y salidas

Salidas: summary (por ejemplo critical=0 warning=1 info=2), report-json (la ruta del reporte JSON dentro de RUNNER_TEMP) y sarif (la ruta del archivo SARIF, solo cuando sarif está activado). Con mode: pr, también pr-url y pr-action.

Se requiere auth o un fixture

La action necesita una de dos entradas y, si no defines ninguna, nombra ambas.

• auth: tu secreto KEDGEWAY_AUTH, para datos en vivo de Raven. Expórtalo con kedgeway login --export.
• fixture: un snapshot incluido en un commit (consulta Fixtures). Sin conexión y determinista; tú lo actualizas.

Anotaciones

Con annotations activado, que es el valor por defecto cuando la action corre en GitHub, cada hallazgo se convierte en un comando de workflow que apunta a la línea de la dependencia en su manifiesto. Critical es ::error, warning es ::warning e info es ::notice. En un pull request aparecen sobre los archivos modificados del diff. No hace falta ningún permiso ni paso adicional.

• GitHub limita las anotaciones a 10 por tipo (error, warning, notice) por paso y a 50 por job. En un repo grande solo se ven las primeras; el reporte completo se sigue imprimiendo en el log.
• Los hallazgos que no se refieren a un archivo, como DATA_DEGRADED y NO_SDK_FOUND, no tienen archivo y aparecen en la ejecución.
• La línea sale de un escaneo simple del manifiesto (la primera clave que coincide), así que es aproximada. Las rutas son relativas al directorio desde el que corre la action.
• El texto de los hallazgos se sanea antes de imprimirse, así que un manifiesto no puede inyectar comandos de workflow.

Fuera de Actions, usa kedgeway diagnose --format annotations o --annotations <file>. Consulta Comandos. SARIF, más abajo, es independiente y se mantiene: alimenta code scanning, y las anotaciones alimentan el diff.

Abrir un PR de migración

Con mode: pr, la action ejecuta kedgeway pr: cuando tus versiones del SDK están atrasadas, publica la rama kedgeway/migrate-<major> y abre un único pull request con los cambios, los hallazgos, los pasos manuales como lista de tareas y la guía de migración. Las ejecuciones siguientes actualizan el mismo pull request. Cuando no hay nada que editar, la ejecución se omite. La entrada repo no se admite en este modo, porque un pull request necesita el checkout local. Consulta Comandos para ver el flujo completo.

kedgeway init --mode pr

name: kedgeway-pr

on:
  schedule:
    - cron: "0 9 * * 1"
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

concurrency:
  group: kedgeway-pr
  cancel-in-progress: false

jobs:
  kedgeway-pr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: false
      - uses: Klorenn/kedgeway@v0.3.0
        with:
          mode: pr
          auth: ${{ secrets.KEDGEWAY_AUTH }}

kedgeway init --mode pr escribe este archivo como .github/workflows/kedgeway-pr.yml, fijado a la versión instalada. Se ejecuta cada lunes a las 09:00 UTC y a pedido. Agrega el secreto KEDGEWAY_AUTH igual que para diagnose.

Necesita:

• permissions: contents: write y pull-requests: write en el workflow o en el job. El archivo generado ya los define.
• actions/checkout con fetch-depth: 0, para que el historial de la rama base esté disponible al crear la rama.
• persist-credentials: false en el checkout, para que no quede ningún token en .git/config. El workflow generado lo define.
• Un grupo de concurrency, kedgeway-pr, para que dos ejecuciones nunca se solapen. El workflow generado lo define.
• Un host de push que sea github.com, o el host de GITHUB_API_URL en GitHub Enterprise Server. Si no, la ejecución termina con código 2 y el token nunca se envía.
• Con refresh-lockfiles, Yarn 1 se omite y Yarn 2+ se ejecuta con los scripts desactivados.
• La opción del repositorio "Allow GitHub Actions to create and approve pull requests" (Settings, Actions, General, Workflow permissions). Una organización tiene que permitirla primero a nivel de organización. Sin ella, GitHub responde 403; kedgeway imprime el mensaje de GitHub con una pista que apunta a esta opción y termina con código 1.

Con mode: pr, la action también define pr-url (el pull request que se creó o se actualizó; vacío si se omitió) y pr-action (create, update o skip).

SARIF y code scanning

permissions:
  contents: read
  security-events: write
steps:
  - uses: actions/checkout@v4
  - id: kedgeway
    uses: Klorenn/kedgeway@v0.1.0
    with:
      auth: ${{ secrets.KEDGEWAY_AUTH }}
      sarif: "true"
      fail-on: ""            # let the upload step report instead of failing here
  - uses: github/codeql-action/upload-sarif@v3
    if: always()
    with:
      sarif_file: ${{ steps.kedgeway.outputs.sarif }}

El log tiene una ejecución para la herramienta kedgeway, una regla por código de hallazgo (18) y un resultado por hallazgo con la ruta del manifiesto relativa al repo. Critical es un error, warning es una advertencia e info es una nota. Los hallazgos que no se refieren a un archivo, como DATA_DEGRADED y NO_SDK_FOUND, no tienen ubicación.

Códigos de salida y velocidad

La action ejecuta diagnose una vez, siempre escribe sus salidas y termina con el código de la CLI: 0 cuando nada alcanzó el umbral, 2 cuando un hallazgo lo alcanzó y 1 ante un error de la herramienta. Fijar un tag de release (uses: Klorenn/kedgeway@v1.2.3) instala exactamente esa versión desde npm sin paso de build, y falla con un error claro si la versión no está publicada. Cualquier otra ref (@main, un SHA de commit, una rama) compila el código fuente del checkout con npm ci && npm run build, que es más lento, y @main no está fijado. La instalación desde npm aplica a los tags creados después de este cambio; v0.1.0 todavía compila desde el código fuente.

Con mode: pr ejecuta kedgeway pr en su lugar: termina con código 0 si el pull request se creó o se actualizó, o si la ejecución se omitió; con código 1 ante una falla de git o de la API; con código 2 ante un error de uso.