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
- Valide los archivos de workflow en el editor y en un hook de pre-commit.
- Copie pasos de workflows que funcionen en lugar de escribir la estructura de memoria.
- Mantenga los workflows pequeños y mueva la lógica compartida a workflows reutilizables o a acciones compuestas.
- 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.
Relacionado
- Rechazo de GitHub App para actualizar el flujo: soluciónCorrija «refusing to allow a GitHub App to create or update workflow without workflows permission» con un PAT o token de App con permiso de escritura.
- ¿Qué es un workflow reutilizable en GitHub Actions?Un flujo reutilizable es un workflow de GitHub Actions que otros flujos pueden llamar con inputs y secrets. Sintaxis de workflow_call y errores comunes.
- ¿Qué es workflow_dispatch en GitHub Actions?workflow_dispatch es el disparador de GitHub Actions que inicia un flujo manualmente con inputs. Sintaxis, uso con CLI y API, y errores comunes.
- Cache Service Responded With 429: Cómo solucionarloSolucione "Failed to restore: Cache service responded with 429" en GitHub Actions: demasiadas solicitudes de caché. Actualice actions/cache y restaure y guarde una vez.