¿Qué es un workflow reutilizable en GitHub Actions?
Última actualización
Un workflow reutilizable es un archivo de workflow de GitHub Actions que otros workflows pueden llamar como si fuera un único job. Declara el disparador workflow_call, recibe inputs y secrets, y puede devolver outputs, de modo que los equipos definen un pipeline una vez y lo reutilizan en distintos repositorios.
Cómo funciona
El workflow llamado indica on: workflow_call con inputs, secrets y outputs opcionales. El workflow que llama añade un job con uses: que apunta al archivo, ya sea en el mismo repositorio (./.github/workflows/ci.yml) o en otro (org/repo/.github/workflows/ci.yml@ref), y pasa valores con with: y secrets:.
El workflow llamado ejecuta sus propios jobs en sus propios runners. Su runs-on se define dentro de él, así que para trasladar un pipeline compartido a máquinas más rápidas basta con modificar un solo archivo, no cada repositorio.
Un workflow reutilizable es distinto de una acción compuesta. Una acción compuesta agrupa pasos dentro de un único job. Un workflow reutilizable agrupa jobs completos, con sus propios runners, matrices y servicios.
Ejemplo
Workflow llamado, .github/workflows/node-ci.yml en acme/shared:
on:
workflow_call:
inputs:
node-version:
type: string
default: "22"
secrets:
NPM_TOKEN:
required: false
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
cache: npm
- run: npm ci && npm test
Caller:
jobs:
ci:
uses: acme/shared/.github/workflows/node-ci.yml@v1
with:
node-version: "20"
secrets: inherit
Errores comunes
- Referencias sin fijar.
@mainsignifica que cualquier push al repositorio compartido cambia a todos los que lo llaman. Fije una etiqueta o un SHA. - Anidamiento demasiado profundo. Existe un límite en el número de niveles de workflows reutilizables que pueden llamarse entre sí.
- Esperar que
envse transmita. Las variables de entorno definidas en el workflow que llama no son visibles en el workflow llamado. Pase los inputs. - Los secrets no llegan al workflow llamado. Páselos explícitamente o use
secrets: inheritdonde esté permitido. - Sorpresas con los permisos. El workflow llamado no puede obtener más permisos de
GITHUB_TOKENque los que conceda el workflow que llama. - Ocultar una compilación con matriz dentro de él sin exponer inputs, de modo que quienes llaman no puedan ajustarla.
Los workflows reutilizables también ayudan a mantener grupos de concurrencia y configuraciones de seguridad coherentes. Consulte cómo proteger GitHub Actions para recomendaciones sobre el fijado de versiones.
Términos relacionados
Preguntas frecuentes
¿Puede un repositorio privado compartir workflows?
Sí, siempre que la configuración de acceso a Actions del repositorio permita que otros repositorios de la organización los usen.
¿Cómo se factura?
Los jobs del workflow llamado consumen minutos como cualquier otro job. Llamarlo no supone ningún cargo adicional.
¿En qué se diferencia de una plantilla?
Una plantilla se copia. Un workflow reutilizable se referencia, por lo que las actualizaciones llegan a quienes lo llaman según la referencia que haya fijado.
Relacionado
- Archivo de flujo de trabajo no válido: cómo solucionar el error de sintaxis YAMLCorrija "Invalid workflow file" y "You have an error in your yaml syntax" en GitHub Actions: sangría, valor inesperado, expresiones erróneas, con actionlint.
- 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 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.
- ¿Qué son los minutos de CI? Facturación de GitHub ActionsLos minutos de CI son el tiempo de cómputo facturado que usan sus pipelines. Cómo GitHub Actions cuenta los minutos y reduzca su consumo.