Reutilizar flujos de trabajo

Resumen

En vez de copiar y pegar desde un flujo de trabajo hacia otro, puedes hacer flujos de trabajo reutilizables. Tú y cualquiera que tenga acceso a un flujo de trabajo reutilizable pueden entonces llamarlo desde otro flujo.

El reutilizar flujos de trabajo evita la duplicación. Esto hace que los flujos de trabajo se puedan mantener más fácilmente y te permite crear flujos de trabajo nuevos más fácilmente compilando sobre el trabajo de los demás, tal como lo haces con las acciones. La reutilización de flujos de trabajo también promueve las mejores prácticas al ayudarte a utilizar los flujos de trabajo que están bien diseñados, que ya se han probado y cuya efectividad ya se comprobó. Tu organización puede crear una librería de flujos de trabajo reutilizables que puede mantenerse centralmente.

El siguiente diagrama muestra tres jobs de compilación en la parte izquierda del mismo. Después de que cada uno de estos jobs se complete con éxito, se ejecutará un job dependiente llamado "Deploy". Este job crea un flujo de trabajo reutilizable que contiene tres jobs: "Staging", "Review" y "Production". El job de despliegue "Production" solo se ejecuta después de que el job "Staging" se haya completado con éxito. El utilizar un flujo de trabajo reutilizable para ejecutar jobs de despliegue te permite ejecutarlos para cada compilación sin duplicar el código en los flujos de trabajo.

A un flujo de trabajo que utiliza otro flujo de trabajo se le llama flujo de trabajo "llamante". El flujo de trabajo reutilizable es un flujo "llamado". Un flujo de trabajo llamante puede utilizar varios flujos de trabajo llamados. Cada flujo de trabajo llamado se referencia en una línea simple. El resultado es que el archivo de flujo de trabajo llamante podrá contener solo unas cuantas líneas de YAML, pero podría realizar una cantidad grande de tareas cuando se ejecute. Cuando reutilizas un flujo de trabajo, se utiliza todo el flujo de trabajo llamado justo como si fuera parte del flujo de trabajo llamante.

Si utilizas un flujo de trabajo desde un repositorio diferente, cualquier acción en el flujo de trabajo llamado se ejecutará como si fuera parte del llamante. Por ejemplo, si el flujo de trabajo llamado utiliza actions/checkout, la acción verifica el contenido del repositorio que hospeda el flujo de trabajo llamante y no el llamado.

Cuando un flujo de trabajo llamante activa uno reutilizable, el contexto github siempre se asocia con el flujo llamante. Se otorga acceso automáticamente al flujo de trabajo llamado para github.token y secrets.GITHUB_TOKEN. Para obtener más información sobre el contexto github, consulta la sección "Sintaxis de contexto y expresión para GitHub Actions".

You can view the reused workflows referenced in your GitHub Actions workflows as dependencies in the dependency graph of the repository containing your workflows. Para obtener más información, consulta la sección "Acerca de la gráfica de dependencias".

Flujos de trabajo reutilizables e iniciales

Los flujos de trabajo iniciales permiten que toda persona en tu organización que tenga permiso para crear flujos de trabajo lo haga de forma más fácil y rápida. Cuando las personas crean un flujo de trabajo nuevo, pueden elegir un flujo de trabajo inicial y parte o todo el trabajo de escribir dicho flujo de trabajo se hará automáticamente. Dentro de un flujo de trabajo inicial, también puedes referenciar los flujos de trabajo reutilizables para hacer más fácil que las personas se beneficien de reutilizar el código de flujo de trabajo que se administra centralmente. Si utilizas un nombre de rama o etiqueta cuando referencias el flujo de trabajo reutilizable, puedes garantizar que todo aquél que reutilice ese flujo de trabajo siempre estará utilizando el mismo código de YAML. Sin embargo, si referencias un flujo de trabajo reutilizable mediante una etiqueta o rama, asegúrate de que puedas confiar en esa versión del flujo de trabajo. Para obtener más información, consulta la sección "Fortalecimiento de seguridad para las GitHub Actions".

Para obtener más información, consulta la sección "Crear flujos de trabajo iniciales para tu organización".

Acceso a los flujos de trabajo reutilizables

Un flujo de trabajo reutilizable puede utilizar otro de ellos si cualquiera de las siguientes condiciones es verdadera:

• Ambos flujos de trabajo están en el mismo repositorio.
• El flujo de trabajo llamado se almacena en un repositorio público.

Utilizar ejecutores

Utilizar los ejecutores hospedados en GitHub

La asignación de ejecutores hospedados en GitHub siempre se evalúa utilizando únicamente el contexto del llamante. La facturación de los ejecutores hospedados en GitHub siempre se asocia con el llamador. El flujo de trabajo llamante no puede utilizar ejecutores hospedados en GitHub desde el repositorio llamado. Para obtener más información, consulta la sección "Acerca de los ejecutores hospedados en GitHub".

Utilizar ejecutores auto-hospedados

Called workflows that are owned by the same user or organization as the caller workflow can access self-hosted runners from the caller's context. Esto significa que el flujo de trabajo llamado puede acceder a los ejecutores auto-hospedados que están:

• En el repositorio del llamador
• En la organización, de la organización del repositorio, siempre y cuando se haya hecho disponible al ejecutor para el repositorio llamante

Limitaciones

• Los flujos de trabajo reutilizables no pueden llamar a otros que también sean reutilizables.
• Los flujos de trabajo solo podrán usar a los reutilizables que se encuentren almacenados en un repositorio privado en caso de que estos también se encuentren en el mismo repositorio.
• Ninguna variable de ambiente que se configure en un contexto de env que se defina a nivel del flujo de trabajo en aquél llamante se propagará al flujo llamado. Para obtener más información sobre el contexto env, consulta la sección "Sintaxis de contexto y expresión para GitHub Actions".
• La propiedad strategy no es compatible en ningún job que llame a un flujo de trabajo reutilizable.

Crear un flujo de trabajo reutilizable

Los flujos de trabajo reutilizables son archivos con formato YAML, muy similares a cualquier otro archivo de flujo de trabajo. Tal como con otros flujos de trabajo, puedes ubicar los reutilizables en el directorio .github/workflows de un repositorio. Los subdirectorios del directorio workflows no son compatibles.

Para que un flujo de trabajo sea reutilizable, los valores de on deben incluir workflow_call:

on:
  workflow_call:

Utilizar entradas y secretos en un flujo de trabajo reutilizable

Puedes definir entradas y secretos, las cuales pueden pasarse desde el flujo de trabajo llamante y luego utilizarse dentro del flujo llamado. Existen tres etapas para utilizar una entrada o un secreto en un flujo de trabajo reutilizable.

1. En el flujo de trabajo reutilizable, utiliza las palabras clave inputs y secrets para definir entradas o secretos que se pasarán desde un flujo de trabajo llamante.

   on:
     workflow_call:
       inputs:
         username:
           required: true
           type: string
       secrets:
         envPAT:
           required: true
   

   Para encontrar los detalles de la sintaxis para definir entradas y secretos, consulta on.workflow_call.inputs y on.workflow_call.secrets.

2. Referencia la entrada o secreto ene l flujo de trabajo reutilizable.

   jobs:
     reusable_workflow_job:
       runs-on: ubuntu-latest
       environment: production
       steps:
         - uses: ./.github/workflows/my-action
           with:
             username: ${{ inputs.username }}
             token: ${{ secrets.envPAT }}
   

   En el ejemplo anterior, envPAT es un secreto de ambiente que se ha agregado al ambiente de production. Por lo tanto, este ambiente se referencia dentro del job.

   Note: Los secretos de ambiente son secuencias cifradas que se almacenan en un ambiente que hayas definido para un repositorio. Los secretos de ambiente solo se encuentran disponibles para los jobs de flujo de trabajo que referencian al ambiente adecuado. Para obtener más información, consulta la sección "Utilizar ambientes para despliegue".

3. Pasa la entrada o secreto desde el flujo de trabajo llamante.

   To pass named inputs to a called workflow, use the with keyword in a job. Utiliza la palabra clave secrets para pasar los secretos nombrados. For inputs, the data type of the input value must match the type specified in the called workflow (either boolean, number, or string).

   jobs:
     call-workflow-passing-data:
       uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
       with:
         username: mona
       secrets:
         envPAT: ${{ secrets.envPAT }}
   

Flujo de trabajo reutilizable de ejemplo

Este flujo de trabajo reutilizable llamado workflow-B.yml (al cual nos referiremos más adelante en el flujo de trabajo llamante de ejemplo) toma un secreto y secuencia de entrada desde el flujo de trabajo llamante y los utiliza en una acción.

name: Reusable workflow example

on:
  workflow_call:
    inputs:
      username:
        required: true
        type: string
    secrets:
      token:
        required: true

jobs:
  example_job:
    name: Pass input and secrets to my-action
    runs-on: ubuntu-latest
    steps:
      - uses: ./.github/workflows/my-action
        with:
          username: ${{ inputs.username }}
          token: ${{ secrets.token }}

Llamar a un flujo de trabajo reutilizable

Se llama a un flujo de trabajo reutilizable utilizando la palabra clave uses. A diferencia de cuando utilizas acciones en un flujo de trabajo, los flujos de trabajo reutilizables se llaman directamente desde un job y no dentro de los pasos de un job.

jobs.<job_id>.uses

You reference reusable workflow files using one of the following syntaxes:

• {owner}/{repo}/{path}/{filename}@{ref} for reusable workflows in public repositories.
• ./{path}/{filename} for reusable workflows in the same repository.

{ref} puede ser un SHA, una etiqueta de lanzamiento o un nombre de rama. Utilizar el SHA de la confirmación es lo más seguro para la estabilidad y seguridad. Para obtener más información, consulta la sección "Fortalecimiento de la seguridad para las GitHub Actions". If you use the second syntax option (without {owner}/{repo} and @{ref}) the called workflow is from the same commit as the caller workflow.

Puedes llamar a flujos de trabajo múltiples, referenciando cada uno en un job separado.

jobs:
  call-workflow-1-in-local-repo:
    uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
  call-workflow-2-in-local-repo:
    uses: ./.github/workflows/workflow-2.yml
  call-workflow-in-another-repo:
    uses: octo-org/another-repo/.github/workflows/workflow.yml@v1

Pasar entradas y secretos a un flujo de trabajo reutilizable

To pass named inputs to a called workflow, use the with keyword in a job. Utiliza la palabra clave secrets para pasar los secretos nombrados. For inputs, the data type of the input value must match the type specified in the called workflow (either boolean, number, or string).

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      username: mona
    secrets:
      envPAT: ${{ secrets.envPAT }}

Palabras clave compatibles con los jobs que llaman a un flujo de trabajo reutilizable

Cuando llamas a un flujo de trabajo reutilizable, solo puedes utilizar las siguientes palabras clave en el job que contiene la llamada:

• jobs.<job_id>.name

• jobs.<job_id>.uses

• jobs.<job_id>.with

• jobs.<job_id>.with.<input_id>

• jobs.<job_id>.secrets

• jobs.<job_id>.secrets.<secret_id>

• jobs.<job_id>.needs

• jobs.<job_id>.if

• jobs.<job_id>.permissions

  Nota:

  • Si no se especifica jobs.<job_id>.permissions en el job de llamada, el flujo de trabajo llamado tendrá los permisos predefinidos para el GITHUB_TOKEN. Para obtener más información, consulta la sección "Autenticación en un flujo de trabajo".

  • Los permisos del GITHUB_TOKEN que se pasaron del flujo de trabajo llamante solo pueden bajarse de nivel (no elevarse) a través del flujo de trabajo llamado.

Flujo de trabajo llamante de ejemplo

Este archivo de flujo de trabajo llama a otros dos archivos de flujo de trabajo. Al segundo de estos, workflow-B.yml (el cual se muestra en el flujo de trabajo reutilizable de ejemplo), se le pasa una entrada (username) y un secreto (token).

name: Call a reusable workflow

on:
  pull_request:
    branches:
      - main

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/workflow-A.yml@v1

  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/workflow-B.yml@main
    with:
      username: mona
    secrets:
      token: ${{ secrets.TOKEN }}

Utilizar salidas desde un flujo de trabajo reutilizable

Un flujo de trabajo reutilizable podría generar datos que quieras utilizar en el flujo de trabajo llamante. Para utilizar estas salidas, debes especificarlas como las salidas del flujo de trabajo reutilizable.

Los siguientes flujos de trabajo reutilizables tienen un solo job que contiene dos pasos. En cada uno de estos pasos, configuramos una sola palabra como la salida: "hello" y "world". En la sección de outputs del job, mapeamos estas salidas de paso a las salidas de jobs llamadas: output1 y output2. En la sección de on.workflow_call.outputs, definimos entonces a las dos salidas del mismo flujo de trabajo, una llamada firstword, la cual mapeamos a output1, y otra llamada secondword, la cual mapeamos a output2.

name: Reusable workflow

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      firstword:
        description: "The first output string"
        value: ${{ jobs.example_job.outputs.output1 }}
      secondword:
        description: "The second output string"
        value: ${{ jobs.example_job.outputs.output2 }}

jobs:
  example_job:
    name: Generate output
    runs-on: ubuntu-latest
    # Map the job outputs to step outputs
    outputs:
      output1: ${{ steps.step1.outputs.firstword }}
      output2: ${{ steps.step2.outputs.secondword }}
    steps:
      - id: step1
        run: echo "::set-output name=firstword::hello"
      - id: step2
        run: echo "::set-output name=secondword::world"

Ahora podemos utilizar las salidas en el flujo de trabajo llamante, de la misma forma en la que utilizarías las salidas de un job dentro del mismo flujo de trabajo. Referenciamos las salidas utilizando los nombres que se definen a nivel del flujo de trabajo en el reutilizable: firstword y secondword. En este flujo de trabajo, job1 llama al flujo de trabajo reutilizable y job2 imprime las salidas desde el flujo de trabajo reutilizable ("hello world") en una salida estándar en la bitácora del mismo.

name: Call a reusable workflow and use its outputs

on:
  workflow_dispatch:

jobs:
  job1:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@v1

  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo ${{ needs.job1.outputs.firstword }} ${{ needs.job1.outputs.secondword }}

Para obtener más información sobre cómo utilizar las salidas de los jobs, consulta la sección "Sintaxis de flujo de trabajo para las GitHub Actions".

Monitorear qué flujos de trabajo se están utilizando

Puedes utilizar la API de REST de GitHub para monitorear cómo se utilizan los flujos de trabajo reutilizables. La acción de bitácora de auditoría prepared_workflow_job se activa cuando se inicia un job de flujo de trabajo. Entre los datos registrados se incluyen:

• repo - la organización/repositorio en donde se ubica el job de flujo de trabajo. Para un job que llama a otro flujo de trabajo, esta es la organización/repositorio del flujo llamador.
• @timestamp - la fecha y hora en las que se inició el job, en formato epoch de Unix.
• job_name - el nombre del job que se ejecutó.
• job_workflow_ref - el flujo de trabajo que se utilizó, en formato {owner}/{repo}/{path}/{filename}@{ref}. Para un job que llama a otro flujo de trabajo, esto identifica al flujo llamado.

Para obtener más información sobre cómo utilizar la API de REST para consultar la bitácora de auditoría de una organización, consulta la sección "Organizaciones".

Pasos siguientes

Para seguir aprendiendo sobre las GitHub Actions, consulta la sección "Eventos que activan flujos de trabajo".