Reusable workflows

Un reusable workflow es un workflow completo que otros workflows pueden invocar como si fuera un bloque. En vez de copiar la definición de un pipeline de deploy en veinte repos, la escribís una vez y la llamás desde cada uno. Es el siguiente escalón sobre las composite actions del capítulo anterior.

Definir un reusable workflow

Se convierte un workflow en reusable agregándole el evento workflow_call, con inputs y secrets tipados que declaran su interfaz pública:

# .github/workflows/deploy.yml (el reusable)
on:
  workflow_call:
    inputs:
      entorno:
        type: string
        required: true
    secrets:
      TOKEN_DEPLOY:
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploy a ${{ inputs.entorno }}"

Invocarlo

Se llama desde la clave uses: a nivel de job (no de step). La sintaxis depende de dónde viva el reusable:

# el caller
jobs:
  llamar-deploy:
    uses: mi-org/mi-repo/.github/workflows/deploy.yml@v1
    with:
      entorno: production
    secrets:
      TOKEN_DEPLOY: ${{ secrets.TOKEN_DEPLOY }}

• Otro repo: {owner}/{repo}/.github/workflows/{archivo}@{ref} (el @ref es obligatorio: un tag, rama o SHA).
• Mismo repo: ./.github/workflows/{archivo} (ruta relativa, sin @ref).

Pasaje de secrets

Este es un punto que sorprende: los secrets no se heredan automáticamente hacia el reusable workflow. Un secret de environment del caller no llega solo al workflow llamado; hay que pasarlo de forma explícita. Dos opciones:

# Opción 1: heredar todos los secrets del caller
    secrets: inherit

# Opción 2: mapeo explícito, uno por uno
    secrets:
      TOKEN_DEPLOY: ${{ secrets.TOKEN_DEPLOY }}

secrets: inherit pasa todos los secrets disponibles en el caller; el mapeo explícito es más seguro porque entrega solo lo necesario.

Límites

Límite	Valor (GitHub.com / GHEC)
Profundidad de anidamiento	Hasta 10 niveles (un reusable que llama a otro reusable)
Reusable workflows únicos por archivo	Máximo 50

Nota on-premise: estos son los límites vigentes en GitHub.com y GitHub Enterprise Cloud. Versiones más antiguas de GitHub Enterprise Server (p. ej. 3.16) tienen límites menores — del orden de 4 niveles de anidamiento y 20 workflows por archivo. Si estás en un GHES antiguo, verificá los valores de tu versión.

Reusable workflow vs composite action

Ambos combaten la repetición, pero operan en niveles distintos:

	Reusable workflow	Composite action
Qué define	Uno o más jobs completos	Una secuencia de steps
Runner	Cada job estrena su propio runner	Corre dentro de un job existente
Se invoca desde	jobs.<id>.uses: (nivel job)	steps con uses: (nivel step)
Ubicación	.github/workflows/*.yml	.github/actions/<nombre>/action.yml
Cuándo usarlo	Reutilizar un pipeline entero (build+test+deploy)	Reutilizar unos pocos steps dentro de un job

flowchart TD
    subgraph RW["Reusable workflow"]
        direction TB
        RWj1["job build (runner propio)"]
        RWj2["job deploy (runner propio)"]
    end
    subgraph CA["Composite action"]
        direction TB
        CAs["step A → step B → step C<br/>(dentro de un job del caller)"]
    end

La regla práctica: si querés reutilizar jobs enteros con su propio runner, es un reusable workflow; si querés reutilizar un puñado de steps dentro de un job que ya existe, es una composite action.

---

Anterior → Capítulo 4: Actions avanzado · Siguiente → Capítulo 6: Seguridad en Actions