Personalización del flujo de trabajo con variables de entorno y datos de artefacto

  • 12 minutos

Aquí, aprenderá a usar variables de entorno predeterminadas y personalizadas, scripts personalizados y dependencias de caché, y a pasar datos de artefacto entre trabajos. También aprenderá a acceder a los registros de flujo de trabajo desde el sitio web de GitHub y puntos de conexión de API REST.

Variables de entorno y contextos predeterminados

Dentro del flujo de trabajo de Acciones de GitHub, hay varias variables de entorno predeterminadas disponibles para usar, pero solo dentro del ejecutor que ejecuta un trabajo. Estas variables predeterminadas distinguen mayúsculas de minúsculas y hacen referencia a los valores de configuración del sistema y al usuario actual. Se recomienda usar estas variables de entorno predeterminadas para hacer referencia al sistema de archivos en lugar de usar rutas de acceso de archivo codificadas de forma rígida. Para usar una variable de entorno predeterminada, especifique $ seguido del nombre de la variable de entorno.

jobs:
  prod-check:
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Además de las variables de entorno predeterminadas, puede usar variables definidas como contextos. Los contextos y las variables predeterminadas son similares, ya que proporcionan acceso a la información del entorno, pero tienen algunas diferencias importantes. Mientras que las variables de entorno predeterminadas solo se pueden usar dentro del ejecutor, las variables de contexto se pueden utilizar en cualquier punto del flujo de trabajo. Por ejemplo, las variables de contexto permiten ejecutar una instrucción if para evaluar una expresión antes de ejecutar el ejecutor.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

En este ejemplo se usa el contexto github.ref para comprobar la rama que ha desencadenado el flujo de trabajo. Si la rama es main, se ejecuta el ejecutor y se imprime "Deploying to production server on branch $GITHUB_REF" (Implementación en el servidor de producción en la rama $GITHUB_REF). La variable de entorno $GITHUB_REF predeterminada se usa en el ejecutor para hacer referencia a la rama. Tenga en cuenta que las variables de entorno predeterminadas están en mayúsculas, mientras que las variables de contexto están en minúsculas.

Variables de entorno personalizadas

De forma similar al uso de variables de entorno predeterminadas, en el archivo de flujo de trabajo puede utilizar variables de entorno personalizadas. Para crear una variable personalizada, debe definirla en el archivo de flujo de trabajo mediante el contexto env. Si quiere usar el valor de una variable de entorno dentro de un ejecutor, puede utilizar el método normal del sistema operativo del ejecutor para leer variables de entorno.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Nice work, $First_Name. Deploying to production server on branch $GITHUB_REF"
        env:
          First_Name: Mona

Scripts en el flujo de trabajo

En los ejemplos de fragmentos de flujo de trabajo anteriores, se usa la palabra clave run para imprimir simplemente una cadena de texto. Como la palabra clave run indica al trabajo que ejecute un comando en el ejecutor, se usa la palabra clave run para ejecutar acciones o scripts.

jobs:
  example-job:
    steps:
      - run: npm install -g bats

En este ejemplo, se usa npm para instalar el paquete de pruebas de software bats con la palabra clave run. También puede ejecutar un script como una acción. Puede almacenar el script en el repositorio, normalmente en un directorio .github/scripts/ y, después, proporcionar la ruta de acceso y el tipo de shell mediante la palabra clave run.

jobs:
  example-job:
    steps:
      - name: Run build script
        run: ./.github/scripts/build.sh
        shell: bash

Dependencias de caché con la acción de caché

Al compilar un flujo de trabajo, a menudo tendrá que reutilizar las mismas salidas o descargar dependencias de una ejecución a otra. En lugar de descargar estas dependencias una y otra vez, puede almacenarlas en caché para que el flujo de trabajo se ejecute de forma más rápida y eficaz. Esto puede reducir drásticamente el tiempo necesario para ejecutar determinados pasos en un flujo de trabajo, ya que los trabajos en ejecutores hospedados en GitHub siempre se inician en un entorno virtual limpio. El almacenamiento en caché de las dependencias ayudará a acelerar el tiempo necesario para volver a crear estos archivos de dependencia.

Para almacenar en caché las dependencias de un trabajo, use la acción cache de GitHub. Esta acción recupera una caché que se identifica mediante una clave única que debe proporcionar. Cuando la acción encuentra la caché, recupera los archivos almacenados en caché en la ruta de acceso que configure. Para usar la acción cache, tendrá que establecer algunos parámetros específicos:

Parámetro Descripción Requerido
Clave Hace referencia al identificador de clave creado al guardar y buscar una caché. Sí
Ruta de acceso Hace referencia a la ruta de acceso del archivo en el ejecutor que se va a almacenar en caché o buscar. Sí
Claves de restauración Consta de claves existentes alternativas a las cachés si no se encuentra la clave de caché deseada. No 
steps:
  - uses: actions/checkout@v2

  - name: Cache NPM dependencies
    uses: actions/cache@v2
    with:
      path: ~/.npm
      key: ${{ runner.os }}-npm-cache-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-npm-cache-

En el ejemplo anterior, path se establece en ~/.npm y key incluye el sistema operativo del ejecutor y el hash SHA-256 del archivo package-lock.json. La adición de un id. como prefijo a la clave (npm-cache en este ejemplo) es útil cuando se usa la reserva restore-keys y hay varias cachés.

Paso de datos de artefactos entre trabajos

Similar al concepto de almacenamiento en caché de las dependencias dentro del flujo de trabajo, puede pasar datos entre trabajos dentro del mismo flujo de trabajo. Para ello, puede usar las acciones upload-artifact y download-artifact. Para poder ejecutarse, los trabajos que dependen de los artefactos de un trabajo anterior deben esperar a que el trabajo anterior se complete correctamente. Esto resulta útil si tiene una serie de trabajos que se deben ejecutar secuencialmente en función de los artefactos cargados desde un trabajo anterior. Por ejemplo, job_2 necesita job_1 mediante la sintaxis needs: job_1.

name: Share data between jobs
on: push
jobs:
  job_1:
    name: Upload File
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello World" > file.txt
      - uses: actions/upload-artifact@v2
        with:
          name: file
          path: file.txt

  job_2:
    name: Download File
    runs-on: ubuntu-latest
    needs: job_1
    steps:
      - uses: actions/download-artifact@v2
        with:
          name: file
      - run: cat file.txt

El ejemplo anterior tiene dos trabajos. job_1 escribe texto en el archivo file.txt y, después, usa la acción actions/upload-artifact@v2 para cargar este artefacto y almacenar los datos para su uso futuro dentro del flujo de trabajo. job_2 necesita job_1 para completarse mediante la sintaxis needs: job_1, después usa la acción actions/download-artifact@v2 para descargar ese artefacto y luego imprimir el contenido de file.txt.

Habilitación del registro de depuración de pasos en un flujo de trabajo

En algunos casos, los registros de flujo de trabajo predeterminados no proporcionarán suficientes detalles para diagnosticar por qué se ha producido un error en la ejecución, el trabajo o el paso de un flujo de trabajo específico. En estas situaciones, puede habilitar el registro de depuración adicional para dos opciones: ejecuciones y pasos. Habilite este registro de diagnóstico estableciendo dos secretos de repositorio que requieren acceso admin al repositorio en true:

  • Para habilitar el registro de diagnóstico del ejecutor, establezca en true el secreto ACTIONS_RUNNER_DEBUG en el repositorio que contiene el flujo de trabajo.
  • Para habilitar el registro de diagnóstico de pasos, establezca en true el secreto ACTIONS_STEP_DEBUG en el repositorio que contiene el flujo de trabajo.

Acceso a los registros de flujo de trabajo desde la interfaz de usuario

Cuando se piensa en la automatización correcta, el objetivo es dedicar la menor cantidad de tiempo a ver lo que se automatiza para centrar la atención en lo que es relevante. Sin embargo, a veces las cosas no salen según lo previsto y es necesario revisar lo que ha ocurrido. Ese proceso de depuración puede ser frustrante, pero GitHub proporciona una estructura de diseño clara que permite una manera rápida de desplazarse entre los trabajos y mantener el contexto del paso de depuración actual. Para ver los registros de una ejecución de flujo de trabajo en GitHub, puede seguir estos pasos:

  1. Vaya a la pestaña Actions del repositorio.
  2. En la barra lateral izquierda, haga clic en el flujo de trabajo deseado.
  3. En la lista de ejecuciones de flujo de trabajo, seleccione la ejecución deseada.
  4. En Jobs, seleccione el trabajo deseado.
  5. Lea la salida del registro.

Si tiene varias ejecuciones dentro de un flujo de trabajo, también puede seleccionar el filtro Estado después de elegir el flujo de trabajo y establecerlo en Error para mostrar solo las ejecuciones con error dentro de ese flujo de trabajo.

Acceso a los registros de flujo de trabajo desde la API REST

Además de ver los registros mediante GitHub, también puede usar la API REST de GitHub para ver los registros de ejecuciones de flujo de trabajo, volver a ejecutar flujos de trabajo o incluso cancelar ejecuciones de flujo de trabajo. Para ver el registro de una ejecución de flujo de trabajo mediante la API, debe enviar una solicitud GET al punto de conexión de registros. Tenga en cuenta que cualquiera con acceso de lectura al repositorio puede usar este punto de conexión. Si el repositorio es privado, debe usar un token de acceso con el ámbito repo.

Por ejemplo, una solicitud GET para ver un registro de ejecución de flujo de trabajo específico seguiría la ruta de acceso siguiente:

GET /repos/{owner}/{repo}/actions/runs/{run_id}/logs