Saltar al contenido

Archivo de flujo de trabajo no válido: cómo solucionar el error de sintaxis YAML

Última actualización:

Invalid workflow file significa que GitHub no pudo analizar ni validar el YAML de su workflow, así que no se ejecutó ningún job. La ejecución muestra un fallo en rojo sin pasos, y el mensaje indica el archivo y, normalmente, una línea. La causa casi siempre es la indentación, un valor en el lugar equivocado o una expresión mal formada. Esta página enumera los mensajes más comunes y una forma de detectarlos antes de hacer push.

El mensaje exacto

Invalid workflow file: .github/workflows/ci.yml#L12
You have an error in your yaml syntax on line 12
The workflow is not valid. .github/workflows/ci.yml (Line: 14, Col: 9): Unexpected value 'run'
The workflow is not valid. .github/workflows/ci.yml (Line: 8, Col: 5): Required property is missing: runs-on

El número de línea es el lugar donde el analizador detectó el problema. El error real suele estar en la línea anterior.

Causa 1: indentación

YAML usa espacios, nunca tabulaciones. Una clave de paso con una profundidad incorrecta hace que run parezca un hermano de steps:

# Wrong
steps:
  - uses: actions/checkout@v4
  run: npm test

# Right
steps:
  - uses: actions/checkout@v4
  - run: npm test

Causa 2: dos puntos o carácter especial en un valor sin comillas

Un valor que contiene : o que empieza por *, &, !, { o % necesita comillas.

# Wrong
- name: Build: release
# Right
- name: "Build: release"

Un comando run: con dos puntos está bien si se escribe como bloque:

- run: |
    echo "status: ok"

Causa 3: una clave obligatoria ausente o una clave desconocida

Cada job necesita runs-on (o uses para un workflow reutilizable) y steps. Las claves distinguen mayúsculas y minúsculas, y una errata como step: o runs_on: provoca un fallo. needs: debe nombrar un job que exista en el mismo archivo.

Causa 4: expresiones

Un ${{ sin cerrar, una comilla simple suelta o una función que no existe hacen fallar todo el archivo. Las expresiones en if: pueden escribirse con o sin ${{ }}, pero una expresión que empieza por ! debe ir entre comillas, porque YAML interpreta un ! inicial como una etiqueta:

if: ${{ !cancelled() }}

Las cadenas dentro de expresiones usan comillas simples: ${{ github.ref == 'refs/heads/main' }}.

Causa 5: errores en los disparadores de on:

La clave on: acepta un nombre, una lista o un mapa. Los filtros como branches van debajo del evento:

on:
  push:
    branches: [main]
  pull_request:

No se permite usar branches y branches-ignore para el mismo evento.

Causa 6: contexto no disponible en el lugar donde se usó

Algunos contextos solo existen en ciertos lugares: env no puede usarse en un jobs.<id>.if, y secrets no puede usarse directamente en una expresión if a nivel de job. El mensaje dice "Unrecognized named-value" e indica el contexto.

Deténgalo antes de hacer push

Ejecute un linter de workflows en local. actionlint entiende el esquema, los fragmentos de shell y las expresiones:

docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color

o instálelo con Homebrew (brew install actionlint) y ejecute actionlint. También puede ejecutarlo en CI cuando cambien los archivos de workflow:

- uses: actions/checkout@v4
- run: bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash) && ./actionlint -color

Los editores con la extensión de YAML y el esquema de workflows de GitHub también resaltan los errores mientras escribe.

Cómo prevenirlo

  1. Valide los archivos de workflow en el editor y en un hook de pre-commit.
  2. Copie pasos de workflows que funcionen en lugar de escribir la estructura de memoria.
  3. Mantenga los workflows pequeños y mueva la lógica compartida a workflows reutilizables o a acciones compuestas.
  4. Revise los cambios de workflow en un pull request, donde la ejecución falla de forma visible antes de fusionar.

Preguntas frecuentes

¿Por qué mi workflow no se ejecutó?

Un archivo no válido impide cualquier ejecución. Revise la pestaña Actions en busca de una ejecución fallida con el nombre del archivo, o la anotación en el commit.

¿Por qué GitHub señala la línea equivocada?

El analizador informa del punto donde se detuvo. Revise la línea anterior y la indentación.

¿Puedo validar YAML con un linter de YAML genérico?

Detecta errores de sintaxis, pero no reglas específicas de GitHub como la falta de runs-on. Use actionlint para esas.

Mi archivo es válido pero el job se omite, ¿por qué?

Es un problema distinto: un filtro de disparo, un filtro de rutas o una condición if:. Consulte waiting for a runner si el job está bloqueado en lugar de omitido.