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

Completado

Aquí aprenderá algunas configuraciones comunes dentro de un archivo de flujo de trabajo. También 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 schedule evento permite desencadenar un flujo de trabajo para que se ejecute a horas UTC específicas mediante la sintaxis cron POSIX. Esta sintaxis de cron tiene cinco campos *, y cada campo representa una unidad de tiempo.

Por ejemplo, si desea ejecutar un flujo de trabajo cada 15 minutos, el schedule evento 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 mediante la API REST de GitHub o seleccionando el botón Ejecutar flujo de trabajo en la pestaña Acciones del repositorio en GitHub. Con workflow_dispatch, puede elegir en qué rama desea que se ejecute el flujo de trabajo y establecer opcional inputs que GitHub presenta 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 permite desencadenar un flujo de trabajo para la actividad que se produce fuera de GitHub. Básicamente actúa como una solicitud HTTP al repositorio que pide a GitHub que desencadene un flujo de trabajo a partir de una acción o 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. 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 check_run evento, pero solo para los rerequested tipos de actividad o requested_action .

on:
  check_run:
    types: [rerequested, requested_action]

Repository_dispatch

repository_dispatch es un evento personalizado en Acciones de GitHub que permite que sistemas externos (o incluso otros flujos de trabajo de GitHub) desencadenen manualmente flujos de trabajo mediante el envío de una solicitud POST a la API de GitHub. Permite la automatización flexible y la integración con herramientas, scripts o sistemas externos que necesitan iniciar flujos de trabajo en el repositorio.

Casos de uso

• Desencadene flujos de trabajo desde herramientas externas de CI/CD.

• Coordinar las implementaciones de varios repositorios (por ejemplo, el repositorio A finaliza la compilación → desencadena el repositorio B).

• Inicie la automatización basada en eventos externos (webhooks, alertas de supervisión, trabajos CRON fuera de GitHub).

• Encadene ejecuciones de flujo de trabajo entre repositorios o dentro de monorepos.

Flujo de trabajo de ejemplo que escucha repository_dispatch

name: Custom Dispatch Listener

on:
  repository_dispatch:
    types: [run-tests, deploy-to-prod]  # Optional filtering

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Echo the payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload value: ${{ github.event.client_payload.env }}"

Elementos clave:

• tipos: opcional. Define tipos de eventos personalizados como run-tests, deploy-to-prod, etc.

• github.event.client_payload: Acceso a cualquier otro dato personalizado pasado en el evento de envío.

• github.event.action: nombre del event_type enviado.

Desencadenamiento del evento a través de la API

Debe enviar una solicitud POST al punto de conexión de la API REST de GitHub v3:

POST https://api.github.com/repos/OWNER/REPO/dispatches

Autorización

• Requiere un token de acceso personal (PAT) con el ámbito del repositorio.
• En el caso de las organizaciones, asegúrese de que la configuración de acceso sea adecuada para el token.

Estructura de comandos de ejemplo

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"run-tests","client_payload":{"env":"staging"}}'

Estructura de la carga útil

{
  "event_type": "run-tests",
  "client_payload": {
    "env": "staging"
  }
}

Parámetros

Campo	Tipo	Descripción	Obligatorio
event_type	cuerda / cadena	Un nombre personalizado para el evento. Este nombre se asigna al valor de tipos del desencadenador de flujo de trabajo.	Sí
client_payload	objeto	Carga JSON arbitraria para enviar datos personalizados al flujo de trabajo (github.event.client_payload)	No

desglose de parámetros de Repository_dispatch

Al realizar una solicitud POST al punto de conexión de la API de GitHub, debe pasar un cuerpo JSON con dos parámetros principales:

• tipo_de_evento
• client_payload

tipo_de_evento

Cadena personalizada necesaria que defina usted. GitHub trata este valor como "acción" o "tipo" del envío. Se usa para identificar lo que desencadenó el flujo de trabajo y los flujos de trabajo de filtro que escuchan tipos específicos.

• Formato:

  • Tipo: cadena
  • Ejemplo: "deploy", "run-tests", "sync-db", "build-docker"

• Uso en flujo de trabajo: se usa para escuchar tipos de eventos específicos y acceder al valor dentro del flujo de trabajo. Esto ayuda con la reutilización de un único flujo de trabajo con varios propósitos y hace que la automatización sea más organizada y controlada por eventos.

• Ejemplo:

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"

client_payload

Objeto JSON de forma libre que permite enviar datos personalizados junto con el envío. La estructura se define y es accesible dentro del flujo de trabajo.

• Formato:

  • Tipo: objeto
  • Claves y valores personalizados

• Uso en flujo de trabajo: este objeto se utiliza para implementaciones en múltiples entornos, releases versionadas, o para pasar contexto desde otro sistema o canalización, y permite flujos de trabajo parametrizados, similares a los argumentos de entrada.

• Ejemplo:

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"

Desglose de carga útil de ejemplo

{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

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 condicionales en el flujo de trabajo, debe usar la sintaxis ${{ <expression> }} específica. Esta sintaxis indica a GitHub que evalúe una expresión en lugar de tratarla como una cadena.

Por ejemplo, un flujo de trabajo que usa el if condicional para comprobar si github.ref (la ref de la rama o etiqueta que desencadenó la ejecución del flujo de trabajo) coincide con refs/heads/main. Para continuar, 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 el if condicional, 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 de 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.

Deshabilitar un flujo de trabajo puede ser útil en algunas de las situaciones siguientes:

• 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 una ejecución de flujo de trabajo en curso en la interfaz de usuario de GitHub desde la pestaña Acciones o mediante el punto de conexión DELETE /repos/{owner}/{repo}/actions/runs/{run_id}de la API de GitHub . Tenga en cuenta que, al cancelar una ejecución de flujo de trabajo, GitHub cancela 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, no es necesario volver a crear el mismo flujo de trabajo para cada repositorio. En su lugar, puede promover la coherencia en toda la organización mediante una plantilla de flujo de trabajo definida en el repositorio de .github 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 dentro de la organización, seleccione Nuevo flujo de trabajo y busque la sección de plantilla de flujo de trabajo de la organización titulada "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 aquí.

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á la acción a partir de los últimos cambios de esa rama, lo que puede ser conveniente o no. 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.