GitHub Actions: lint y corrección de workflows YAML

¿Por qué revisar un workflow antes de hacer merge en main?

Un archivo .github/workflows/*.yml que no parsea, o un job sin runs-on, suele verse solo después del push: check rojo, logs de GitHub, review bloqueada. FastMinify no incluye actionlint. El validador GitHub Actions hace controles estructurales en el navegador — on, jobs, steps con run o uses — y el formateador GitHub Actions reindenta el YAML (convención de 2 espacios). El cluster completo está en el hub de herramientas CI/CD. Para automatizar minify JS/CSS en el pipeline, consulta la guía de minificación CI/CD.

Detectar YAML inválido, un on/jobs ausente o un step vacío antes del push

Formatear la indentación de 2 espacios para una review legible

100 % en el navegador — el workflow nunca se envía

Tope de 512 KiB UTF-8, como el resto de herramientas DevOps del sitio

Dejar actionlint (expresiones ${{ }}) y el pin de las actions para la CI

Anatomía de un workflow: qué verifica FastMinify (y qué no)

La forma mínima de un workflow GitHub Actions

Un workflow es un documento YAML único. GitHub exige un disparador on y un map jobs. Cada job necesita un runner (runs-on), un workflow reutilizable (uses), o una lista steps. Cada step debe definir run o uses.

Un solo documento YAML — los documentos múltiples (--- repetidos) se rechazan

La raíz debe ser un mapping, no un escalar ni una lista

Job reutilizable: uses sin steps se acepta; el YAML anidado no se inspecciona en profundidad

Un jobs vacío o una lista steps vacía produce un aviso, no necesariamente un error bloqueante

El panel de resultados cuenta jobs, steps y disparadores on tras un parse correcto

Formatear, validar, actionlint: tres capas, no un solo botón

FastMinify expone dos herramientas. Ninguna es actionlint. Confundir las tres lleva a workflows «válidos» que igual fallan en CI.

Antes

name: CI
on: push
jobs:
 build:
  runs-on: ubuntu-latest
  steps:
  - uses: actions/checkout@v4
  - run: npm test

Después

name: CI
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

Formatear: round-trip js-yaml, indentación de 2 espacios (convención GitHub) — ver format-github-actions

Validar: parse YAML + estructura on / jobs / steps — ver validate-github-actions

actionlint: expresiones ${{ }}, permissions, IDs, lookup de actions — para ejecutar en CI, no en FastMinify

Los comentarios YAML se eliminan al formatear (mismo límite que beautify-yaml) — guarda una copia si dependes de ellos

Un veredicto «estructura OK» no demuestra que actions/checkout@v4 exista ni que la expresión sea segura

Expresiones ${{ }} e inyección: fuera del alcance del navegador

Interpolar un contexto no fiable (github.event.issue.title, una etiqueta de PR) directamente en run: es un clásico de inyección de scripts. FastMinify no evalúa las expresiones y no señala este patrón.

Pasa los valores no fiables vía env:, no interpolándolos en el script

Restringe permissions: al mínimo (contents, pull-requests)

Fija SHA o tags de actions en lugar de un flotante sin revisar

actionlint y una review humana siguen siendo la red de seguridad para este riesgo

El validador FastMinify acepta un step que tenga run o uses — aunque el script sea peligroso

Validar y luego formatear: un workflow concreto

Usar el validador GitHub Actions

Abre el validador GitHub Actions, pega un solo archivo de workflow (máx. 512 KiB) y espera el debounce (~300 ms). El panel muestra un veredicto, las incidencias con índice de línea en errores de parse, y contadores de jobs/steps/triggers. Un campo vacío permanece inactivo — no «inválido».

Controles: on, jobs, runs-on o uses o steps, cada step con run o uses

Sin lookup del marketplace, sin evaluación ${{ }}, sin pin de actions

Jobs reutilizables (uses a nivel de job) aceptados sin steps

Todo queda local — sin cuenta, sin subida a un servidor FastMinify

Formatear el YAML antes de la pull request

El formateador GitHub Actions hace pretty-print vía js-yaml. Pegar, subir o sample: formato automático; tras una edición manual, usa el botón Formatear (⌘↵). La indentación de la UI sigue la convención de 2 espacios. No es un reescritor semántico.

Alinea un gist o un ejemplo de docs mal indentado

Los comentarios # desaparecen en el round-trip — cópialos antes si los necesitas

Encadena format → validate para una review legible y una estructura sana

Para YAML fuera de Actions, usa beautify-yaml en lugar de esta herramienta

Escenario — step sin run ni uses

Un compañero añadió - name: empty step sin script. La CI falla tarde, con un mensaje de GitHub poco legible en el overlay de la PR.

Paso 1: pegar el workflow en validate-github-actions

Abre validate-github-actions. Un veredicto inválido del tipo «step needs run or uses» señala el step vacío.

Paso 2: añadir run o uses

Sustituye el step por uses: actions/checkout@v4 o un run: real. Vuelve a pegar hasta que el panel muestre una estructura válida.

Paso 3: formatear y abrir la PR

Pasa el YAML corregido por format-github-actions, copia y haz commit. Los reviewers leen jobs indentados, no un blob.

Escenario — workflow pegado desde un ticket, indentación rota

Un ejemplo copiado de la documentación de GitHub o de un gist llega con una mezcla de espacios. Ya no ves dónde termina un job.

Paso 1: formatear primero si el archivo es ilegible

Pega en format-github-actions. Este paso no demuestra que el workflow esté estructuralmente completo.

Paso 2: validar el documento indentado

Copia la salida en el validador. Comprueba on, jobs y que cada step tenga una action.

Paso 3: dejar actionlint para la CI

Una vez la forma es OK, la red de expresiones / IDs / marketplace sigue en el pipeline — FastMinify no lo sustituye.

Dejar actionlint (y minify) en la CI

Ejemplo de job actionlint — para fijar en tu repositorio

El navegador sirve el bucle rápido antes de git push. Los equipos mantienen actionlint como gate de merge para las expresiones ${{ }} y las reglas que FastMinify no implementa. El ejemplo sigue el script oficial de descarga de actionlint: fija una versión en tu repo en lugar de un main flotante. Para minificar JS/CSS en el mismo pipeline, consulta la guía de minificación CI/CD.

Ejemplo básico

name: Lint GitHub Actions workflows
on:
  pull_request:
    paths:
      - '.github/workflows/**'
jobs:
  actionlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check workflow files
        run: |
          bash <(curl https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
          ./actionlint -color
        shell: bash

GitLab CI y el resto del hub

Si el repositorio está en GitLab, los equivalentes son format-gitlab-ci y validate-gitlab-ci — la misma idea (YAML + estructura, no un runner). Dockerfile y Compose siguen en el hub DevOps: hacer lint de un Dockerfile, validar Compose y .env.

Conclusión

Pega el workflow, corrige la estructura (on, jobs, steps), reformatea la indentación y luego haz push. FastMinify hace este bucle en local, sin enviar el YAML. No es actionlint: expresiones, permissions avanzadas y existencia de las actions siguen en CI y en review. Para YAML genérico, quédate en beautify-yaml; para GitLab, en el mismo hub CI/CD.

Validar o formatear un workflow GitHub Actions ahora

Valida la estructura antes de cada PR que toque .github/workflows

Formatea para la review, pero espera perder los comentarios YAML

No trates un veredicto FastMinify como luz verde de actionlint

Deja la inyección ${{ }} y el pin de actions en la review + la CI

Encadena validate → format, luego actionlint en el merge