Administración y depuración de flujos de trabajo en Acciones de GitHub

Recuerde que el objetivo es automatizar el proceso de compilación y publicación de código para que las características se actualicen cada vez que un desarrollador agregue un cambio a la base de código.

Para implementar este proceso, aprenderá a:

• Identifique el evento que desencadenó un flujo de trabajo.
• Use los registros de flujo de trabajo de Acciones de GitHub.
• Guardar los artefactos de compilación y acceder a ellos.
• Automatice la adición de una etiqueta a una solicitud de incorporación de cambios después de una revisión.

Identificar el evento que desencadenó un flujo de trabajo

Comprender lo que desencadenó un flujo de trabajo de Acciones de GitHub es fundamental para la depuración, la auditoría y la mejora de las canalizaciones de CI/CD. El tipo de desencadenadores incluye una inserción en una rama, una solicitud de incorporación de cambios creada o actualizada, un trabajo programado o un envío manual. Puede identificar el evento desencadenador examinando la ejecución del flujo de trabajo, los cambios del repositorio y el problema de GitHub relacionado o la solicitud de incorporación de cambios.

¿Qué es un desencadenador de flujo de trabajo?

Un desencadenador de flujo de trabajo es un evento que hace que se ejecute un flujo de trabajo. GitHub admite varios tipos de desencadenadores, entre los que se incluyen:

• push o pull_request (en función de los cambios de código)
• workflow_dispatch (un desencadenador manual)
• schedule (trabajos cron)
• repository_dispatch (sistemas externos)
• Eventos de problema, discusión y solicitud de incorporación de cambios (por ejemplo, issues.opened, pull_request.closed)

Identificación del evento de desencadenador

Puede identificar un evento de desencadenador de flujo de trabajo de varias maneras:

• Use la interfaz de usuario de Acciones de GitHub:

  1. En el repositorio, seleccione la pestaña Acciones .
  2. Seleccione una ejecución de flujo de trabajo.

  Un tipo de evento, como push, pull_requesto workflow_dispatch, aparece en la parte superior del resumen de ejecución del flujo de trabajo.

• Use github.event_name en los registros o en un flujo de trabajo.

  • GitHub expone datos de contexto durante una ejecución de flujo de trabajo. La github.event_name variable indica qué evento desencadenó el flujo de trabajo.

  • Puede imprimir la información en un paso para la depuración:

    -name: Show event trigger
      run: echo "Triggered by ${{ github.event_name }}"
    

• Use los detalles de ejecución del flujo de trabajo:

  • Si inspecciona las ejecuciones de flujo de trabajo mediante programación, como mediante la API, el objeto run incluye una event propiedad que especifica el desencadenador.
  • Puede encontrar la confirmación del algoritmo hash seguro (SHA), el actor y la marca de tiempo para realizar un seguimiento de lo que provocó el desencadenador.

Inferencia del desencadenador de los efectos del repositorio

Es posible que no tenga acceso directo a la ejecución del flujo de trabajo, pero desea deducir lo que desencadenó la ejecución del flujo de trabajo en función de la actividad del repositorio:

Al revisar las marcas de tiempo, la actividad de solicitud de incorporación de cambios y el historial de confirmaciones, a menudo puede identificar qué acción provocó la ejecución del flujo de trabajo.

Para resumir cómo identificar lo que desencadenó un flujo de trabajo:

• Compruebe el resumen de ejecución del flujo de trabajo en la pestaña Acciones .
• Imprima o registre github.event_name dentro del flujo de trabajo para obtener visibilidad.
• Compare las marcas de tiempo y la actividad del repositorio (confirmaciones, solicitudes de incorporación de cambios, problemas) para deducir el desencadenador.
• Use el contexto completo event para una investigación más profunda.

Estos procedimientos le ayudan a depurar, auditar y mejorar la confiabilidad del flujo de trabajo en las canalizaciones de desarrollo e implementación.

Comprender un efecto de flujo de trabajo leyendo su archivo de configuración

Para comprender los efectos de un flujo de trabajo desde la lectura de su archivo de configuración, analice la estructura y el contenido del .yml archivo almacenado en .github/workflows/.

El archivo de configuración de flujo de trabajo especifica la siguiente información sobre el flujo de trabajo:

• Cuando se ejecuta (en la on sección).
• Lo que hace (en jobs y steps).
• Donde se ejecuta (la runs-on sección).
• Por qué se ejecuta (su propósito, como pruebas, implementación o linting).
• Cómo se comporta en condiciones específicas (entorno, filtros, lógica).

Interpretación de un efecto de flujo de trabajo

1. Identifique el desencadenador.

   Para identificar qué acción inició el flujo de trabajo, consulte la on sección del flujo de trabajo.

   Por ejemplo:

   on:
     push:
       branches: [main]
     pull_request:
       types: [opened, synchronize]
     workflow_dispatch:
   

   Este flujo de trabajo de ejemplo:

   • Se ejecuta automáticamente cuando el código se inserta en la rama principal (push).
   • Se ejecuta cuando se crea o actualiza una solicitud de incorporación de cambios (pull_request).
   • Un usuario puede desencadenarlo manualmente (workflow_dispatch).

2. Identifique los trabajos y los pasos del flujo de trabajo.

   Para determinar lo que hace el flujo de trabajo, consulte las jobs secciones y steps del flujo de trabajo.

   Por ejemplo:

   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout code
           uses: actions/checkout@v3
         - name: Install dependencies
           run: npm install
         - name: Run tests
           run: npm test
   

   Este flujo de trabajo de ejemplo:

   • Usa un entorno virtual linux (runs-on).
   • Extrae el código del repositorio (steps>name).
   • Instala las dependencias del proyecto (steps>name).
   • Ejecuta pruebas automatizadas (steps>name).

3. Evalúe el propósito y el resultado del flujo de trabajo.

   Al leer el archivo de configuración, puede describir el resultado previsto del flujo de trabajo:

   "Este flujo de trabajo es una canalización de integración continua (CI). Garantiza que cualquier código nuevo que se inserte en el repositorio o que se envíe a través de la solicitud de incorporación de cambios se pruebe automáticamente. Si se produce un error en las pruebas, la interfaz de usuario del flujo de trabajo de GitHub muestra este resultado para ayudarle a mantener la calidad del código".

4. Identifique o establezca características opcionales que afecten a cómo se ejecuta el flujo de trabajo:

   • env establece variables de entorno.
   • if agrega lógica condicional para ejecutar pasos específicos solo cuando se cumplen los criterios.
   • timeout-minutes o continue-on-error establezca la ejecución del flujo de trabajo y el control de errores.

Diagnóstico de una ejecución de flujo de trabajo con errores

1. En el repositorio, vaya a la pestaña Acciones .

2. Busque la ejecución con errores (normalmente indicada por una X roja).

3. Seleccione el flujo de trabajo con errores para abrir el resumen de ejecución.

4. En los registros de flujo de trabajo, revise el error.

   1. En el resumen de ejecución, expanda cada trabajo y paso hasta que encuentre el que indica un error.

   2. Seleccione el trabajo o el paso para ver sus registros.

   3. Busque:

      • Mensajes de error
      • Seguimientos de pila
      • Códigos de salida

   Por ejemplo, una prueba con errores podría mostrar npm ERR! Test failed o exit code 1.

5. Compruebe el archivo de configuración del flujo de trabajo.

   Use el .yml archivo para determinar:

   • ¿Qué intentaba hacer cada paso?
   • Si hay variables de entorno (env) o condicionales (if) que afectan a la ejecución.
   • Si el error se debe a que falta una dependencia, un error de sintaxis o un paso mal configurado.

   Si se produce un error en un paso, compruebe las siguientes causas:

   • ¿Se instalaron correctamente las dependencias en el paso anterior?
   • ¿Existen archivos de prueba y se pasan localmente?

Escenarios de error comunes

En la tabla siguiente se describen escenarios comunes de error de flujo de trabajo:

Identificación de cómo acceder a los registros de flujo de trabajo en GitHub

1. En el repositorio, vaya a la pestaña Acciones .

2. En la lista de flujos de trabajo, seleccione el flujo de trabajo correspondiente.

   Por ejemplo, si su archivo .yml tiene el siguiente código, aparece un vínculo titulado Flujo de trabajo CI en la lista.

   name: CI Workflow
   

3. Seleccione una ejecución específica.

   En la lista de ejecuciones que muestran el estado, seleccione la marca de tiempo o el mensaje de confirmación de la ejecución específica que desea inspeccionar.

4. Expanda cada trabajo y paso.

   La página de resumen de ejecución muestra los trabajos tal como se definen en el archivo de flujo de trabajo, como la compilación o la prueba:

   1. Seleccione un trabajo para expandirlo.
   2. Dentro del trabajo, expanda pasos individuales, como "Instalar dependencias" o "Ejecutar pruebas".

5. Visualización de la salida del registro.

   Para ver la salida completa del registro, incluidos los registros de consola, los mensajes de error y la información de depuración, seleccione un paso de flujo de trabajo. Puede copiar, buscar y descargar los registros.

En la tabla siguiente se resumen los pasos que se realizan para acceder a los registros de flujo de trabajo:

Registros de acciones para la compilación

Cuando se ejecuta un flujo de trabajo, genera un registro que incluye los detalles de lo que ha ocurrido y los errores o errores de prueba.

Si se produce un error o si se produce un error en una prueba, aparece una X roja en lugar de una marca de verificación verde en los registros. Puede examinar los detalles del error o el fallo para investigar lo que sucedió.

Trabajar con artefactos

Cuando un flujo de trabajo genera algo distinto de una entrada de registro, el producto se denomina artefacto. Por ejemplo, la compilación de Node.js genera un contenedor de Docker que se puede implementar. El contenedor es un artefacto que se puede cargar en el almacenamiento mediante la acción actions/upload-artifact . Puede descargar más adelante el artefacto desde el almacenamiento mediante acciones/download-artifact.

El almacenamiento de un artefacto lo conserva entre trabajos. Cada trabajo usa una nueva instancia de una máquina virtual, por lo que no puede reutilizar el artefacto guardándolo en la máquina virtual. Si necesita el artefacto en otro trabajo, puede cargar el artefacto en el almacenamiento en un trabajo y descargarlo para el otro trabajo.

Almacenamiento de artefactos

Los artefactos se almacenan en el espacio de almacenamiento en GitHub. El espacio es gratuito para los repositorios públicos y algunos almacenamientos son gratuitos para los repositorios privados, en función de la cuenta. GitHub almacena los artefactos durante 90 días.

En el fragmento de código de flujo de trabajo siguiente, observe que en la actions/upload-artifact@main acción hay un path atributo . El valor de este atributo es la ruta de acceso para almacenar el artefacto. En este ejemplo, se especifica public/ para cargar todo en un directorio. Si solo quería cargar un solo archivo, use algo parecido a public/mytext.txt.

  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@main
        with:
          name: webpack artifacts
          path: public/

Para descargar el artefacto para realizar pruebas, la compilación debe completarse correctamente y cargar el artefacto. En el código siguiente, especifique que el trabajo de prueba depende del trabajo de compilación.

test:
    needs: build
    runs-on: ubuntu-latest

En el siguiente fragmento de flujo de trabajo, descargas el artefacto. Ahora el trabajo de prueba puede usar el artefacto para las pruebas.

steps:
    - uses: actions/checkout@v3
    - uses: actions/download-artifact@main
      with:
        name: webpack artifacts
        path: public

Para obtener más información sobre el uso de artefactos en flujos de trabajo, consulte Almacenamiento de datos de flujo de trabajo como artefactos.

Automatización de revisiones en GitHub mediante flujos de trabajo

Además de iniciar un flujo de trabajo a través de eventos de GitHub como push y pull-request, puede ejecutar un flujo de trabajo según una programación o después de algún evento fuera de GitHub.

Es posible que quiera que un flujo de trabajo se ejecute solo después de que un usuario complete una acción específica, como después de que un revisor apruebe una solicitud de incorporación de cambios. En este escenario, puede desencadenar en pull-request-review.

Otra acción que puede realizar es agregar una etiqueta a la pull request. En este caso, use la acción pullreminders/label-when-approved-action.

Por ejemplo:

    steps:
     - name: Label when approved
       uses: pullreminders/label-when-approved-action@main
       env:
         APPROVALS: "1"
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         ADD_LABEL: "approved"

En el env bloque , se establecen las variables de entorno para la acción. Por ejemplo, puede establecer el número de aprobadores necesarios para ejecutar el flujo de trabajo. En este ejemplo, es uno. La secrets.GITHUB_TOKEN variable de autenticación es necesaria porque la acción debe realizar cambios en el repositorio agregando una etiqueta. Por último, escriba el nombre de la etiqueta que se va a agregar.

Agregar una etiqueta podría ser un evento que inicia otro flujo de trabajo, como una combinación. Tratamos este evento en el siguiente módulo, que describe el uso de la entrega continua en Acciones de GitHub.