Configuración de un flujo de trabajo de Acciones de GitHub

10 minutos

Aquí aprenderá algunas configuraciones comunes dentro de un archivo de flujo de trabajo. También puede explorar las categorías de tipos de eventos, deshabilitar y eliminar flujos de trabajo y usar versiones específicas de una acción para los procedimientos recomendados de seguridad.

Configuración de flujos de trabajo para que se ejecuten en eventos programados

Como se ha mencionado anteriormente, puede configurar sus flujos de trabajo para que se ejecuten cuando se produzca una actividad específica en GitHub, cuando se produzca un evento fuera de GitHub o a una hora programada. El evento schedule le permite desencadenar un flujo de trabajo para que se ejecute a horas UTC específicas utilizando la sintaxis de cron POSIX. Esta sintaxis de cron tiene cinco campos *, y cada campo representa una unidad de tiempo.

Diagrama de los cinco campos de unidad de tiempo para programar un evento en un archivo de flujo de trabajo.

Por ejemplo, si quisiera ejecutar un flujo de trabajo cada 15 minutos, el evento schedule tendría el siguiente aspecto:

on:
  schedule:
    - cron:  '*/15 * * * *'

Y si quisiera ejecutar un flujo de trabajo cada domingo a las 3:00, el evento schedule tendría el siguiente aspecto:

on:
  schedule:
    - cron:  '0 3 * * SUN'

También puede usar operadores para especificar un intervalo de valores o para marcar el flujo de trabajo programado. El intervalo más corto con el que se pueden ejecutar los flujos de trabajo programados es una vez cada cinco minutos, y se ejecutan en la última confirmación en la rama de base o predeterminada.

Configuración de los flujos de trabajo para que se ejecuten en eventos manuales

Además de los eventos programados, puede desencadenar manualmente un flujo de trabajo mediante el evento workflow_dispatch. Este evento le permite ejecutar el flujo de trabajo al utilizar la API de REST de GitHub o al seleccionar el botón Ejecutar el flujo de trabajo de la pestaña Acciones dentro de su repositorio en GitHub. Con workflow_dispatch, puede elegir la rama en la que quiere que se ejecute el flujo de trabajo, así como establecer inputs opcionales que GitHub presentará como elementos de formulario en la interfaz de usuario.

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'

Además de workflow_dispatch, puede utilizar la API de GitHub para desencadenar un evento de webhook llamado repository_dispatch. Este evento le permite desencadenar un flujo de trabajo para la actividad que se produce fuera de GitHub y básicamente actúa como una solicitud HTTP en el repositorio que pide a GitHub que desencadene un flujo de trabajo fuera de una acción o un webhook. El uso de este evento manual requiere hacer dos cosas: enviar una solicitud POST al punto de conexión de GitHub /repos/{owner}/{repo}/dispatches con los nombres de evento de webhook en el cuerpo de la solicitud y configurar el flujo de trabajo para que use el evento repository_dispatch.

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/dispatches \
  -d '{"event_type":"event_type"}'

on:
  repository_dispatch:
    types: [opened, deleted]

Configuración de los flujos de trabajo para que se ejecuten en eventos de webhook

Por último, puede configurar un flujo de trabajo para que se ejecute cuando se produzcan eventos específicos de webhook en GitHub. Puede desencadenar la mayoría de los eventos de webhook desde más de una actividad para un webhook, por lo que si existen varias actividades para un webhook, puede especificar un tipo de actividad para desencadenar el flujo de trabajo. Por ejemplo, puede ejecutar un flujo de trabajo para el evento check_run, pero solo para los tipos de actividad rerequested o requested_action.

on:
  check_run:
    types: [rerequested, requested_action]

Uso de palabras clave condicionales

Dentro del archivo de flujo de trabajo, puede tener acceso a la información de contexto y evaluar las expresiones. Aunque las expresiones se utilizan normalmente con la palabra clave if condicional en un archivo de flujo de trabajo para determinar si un paso se debe ejecutar o no, puede usar cualquier contexto y expresión admitidos para crear un condicional. Es importante saber que al usar los condicionales en el flujo de trabajo, debe usar la sintaxis específica ${{ <expression> }}, que indica a GitHub que evalúe una expresión en lugar de que la trate como una cadena.

Por ejemplo, un flujo de trabajo que use el condicional if para comprobar si el elemento github.ref (la rama o la referencia de etiqueta que desencadenó la ejecución del flujo de trabajo) coincide con refs/heads/main para continuar con los pasos siguientes en el flujo de trabajo tendría un aspecto similar al siguiente:

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      ...

Observe que, en este ejemplo, faltan los elementos ${{ }} en la sintaxis. Con algunas expresiones, como en el caso del condicional if, puede omitir la sintaxis de la expresión. GitHub evalúa automáticamente algunas de estas expresiones comunes, pero siempre puede incluirlas en caso de que olvide qué expresiones evalúa automáticamente GitHub.

Para obtener más información sobre la sintaxis y las expresiones del flujo de trabajo, consulte Sintaxis de flujo de trabajo para Acciones de GitHub.

Deshabilitación y eliminación de flujos de trabajo

Después de agregar un flujo de trabajo al repositorio, puede encontrarse en una situación en la que desea deshabilitar temporalmente el flujo de trabajo. Puede impedir que se desencadene un flujo de trabajo sin tener que eliminar el archivo del repositorio, ya sea en GitHub o a través de la API REST de GitHub. Cuando desee volver a habilitar el flujo de trabajo, puede hacerlo fácilmente con los mismos métodos.

Captura de pantalla de la deshabilitación de un flujo de trabajo en GitHub.

La deshabilitación de un flujo de trabajo puede resultar útil en algunas situaciones, por ejemplo:

Un error en un flujo de trabajo está produciendo demasiadas solicitudes (o estas son erróneas), lo cual incide negativamente en los servicios externos.
Desea pausar temporalmente un flujo de trabajo que no es fundamental y que está consumiendo demasiados minutos en su cuenta.
Quiere pausar un flujo de trabajo que está enviando solicitudes a un servicio que está inactivo.
Está trabajando en una bifurcación y no necesita toda la funcionalidad de algunos flujos de trabajo que incluye (por ejemplo, los flujos de trabajo programados).

También puede cancelar la ejecución de un flujo de trabajo que esté en curso en la interfaz de usuario de GitHub, en la pestaña Acciones, o mediante el punto de conexión de la API de GitHub DELETE /repos/{owner}/{repo}/actions/runs/{run_id}. Tenga en cuenta que cuando se cancela una ejecución de flujo de trabajo, GitHub cancelará todos sus trabajos y pasos dentro de esa ejecución.

Uso del flujo de trabajo de plantilla de una organización

Si tiene un flujo de trabajo que usan varios equipos dentro de una organización, en lugar de volver a crear el mismo flujo de trabajo para cada repositorio, puede promover la coherencia en toda la organización mediante una plantilla de flujo de trabajo que se define en el repositorio .github de la organización. Cualquier miembro de la organización puede usar un flujo de trabajo de plantilla de la organización y cualquier repositorio dentro de esa organización tendrá acceso a esos flujos de trabajo de plantilla.

Para encontrar estos flujos de trabajo, vaya a la pestaña Acciones de un repositorio de la organización, seleccione Nuevo flujo de trabajo y, a continuación, busque la sección de la plantilla de flujo de trabajo de la organización cuyo título haga mención a los flujos de trabajo creados por nombre de organización. Por ejemplo, la organización denominada Mona tiene un flujo de trabajo de plantilla, como se muestra a continuación.

Captura de pantalla de un flujo de trabajo de organización de plantilla denominado saludo y evaluación de prioridades de Mona.

Uso de versiones específicas de una acción

Al hacer referencia a acciones en el flujo de trabajo, se recomienda hacer referencia a una versión específica de dicha acción en lugar de solo a la propia acción. Al hacer referencia a una versión específica, se está protegiendo frente a los cambios inesperados en la acción que podrían interrumpir el flujo de trabajo. A continuación, se muestran varias formas de hacer referencia a una versión específica de una acción:

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

Algunas referencias son más seguras que otras. Por ejemplo, al hacer referencia a una rama específica, se ejecutará esa acción a partir de los últimos cambios de esa rama (y esto es algo que podría o no querer). Al hacer referencia a un número de versión específico o al hash SHA de la confirmación, está siendo más específico sobre la versión de la acción que ejecuta. Para mayor estabilidad y seguridad, le recomendamos que utilice el SHA de confirmación de una acción publicada dentro de sus flujos de trabajo.