Saltar al contenido

¿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. @main significa 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 env se 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: inherit donde esté permitido.
  • Sorpresas con los permisos. El workflow llamado no puede obtener más permisos de GITHUB_TOKEN que 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.

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.