Crea tu primer workflow YAML desde cero

Concepto clave

Un workflow en GitHub Actions es un proceso automatizado que defines en tu repositorio para construir, probar, empaquetar, lanzar o desplegar cualquier proyecto. Piensa en él como una receta de cocina: tienes ingredientes (tu código), pasos específicos (jobs y steps), y condiciones para ejecutarla (eventos como push o pull request).

El archivo YAML es el lenguaje que usa GitHub Actions para describir esta receta. Se almacena en .github/workflows/ y contiene toda la configuración necesaria. A diferencia de herramientas antiguas que requerían servidores dedicados, GitHub Actions ejecuta estos workflows en runners (máquinas virtuales) gestionados por GitHub, lo que elimina la sobrecarga de mantenimiento de infraestructura.

Cómo funciona en la práctica

Vamos a crear un workflow básico que se active con cada push a la rama main. Primero, en tu repositorio, crea la carpeta .github/workflows/ si no existe. Luego, dentro de ella, crea un archivo llamado ci.yml. Este archivo definirá tres elementos clave: el nombre del workflow, los eventos que lo disparan, y los jobs que ejecutará.

Paso a paso: 1) Define el nombre con name. 2) Especifica el evento con on, por ejemplo, push en la rama main. 3) Añade un job llamado build que corra en Ubuntu. 4) Dentro del job, agrega steps para hacer checkout del código y ejecutar un comando simple como un echo. Esto valida que el workflow funciona antes de añadir complejidad.

Código en acción

Aquí tienes un ejemplo funcional de un workflow YAML que se ejecuta en cada push a main y muestra un mensaje:

name: CI Pipeline

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout del código
        uses: actions/checkout@v4
      
      - name: Mostrar mensaje de inicio
        run: echo "Workflow iniciado para el commit ${{ github.sha }}"
      
      - name: Listar archivos
        run: ls -la

Ahora, mejoremos este código añadiendo un paso para instalar dependencias de un proyecto Node.js, mostrando el antes y después:

name: CI Pipeline con Build

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout del código
        uses: actions/checkout@v4
      
      - name: Configurar Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      
      - name: Instalar dependencias
        run: npm ci
      
      - name: Ejecutar tests
        run: npm test

Errores comunes

• Indentación incorrecta en YAML: YAML es sensible a espacios; usa 2 espacios por nivel, no tabs. Un error común es mezclarlos, lo que causa fallos de parsing.
• No especificar versión en actions: Al usar uses: actions/checkout sin versión (ej., @v4), puedes tener comportamientos inesperados. Siempre fija una versión mayor para estabilidad.
• Olvidar el evento on: Si no defines on, el workflow nunca se ejecutará. Asegúrate de incluir eventos como push o pull_request.
• Usar runners incorrectos: Elegir runs-on: windows-latest para un proyecto Linux puede ralentizar el proceso. Selecciona el SO adecuado a tu stack.
• No manejar fallos en steps: Por defecto, si un step falla, el job se detiene. Usa continue-on-error: true en steps opcionales para evitar esto.

Checklist de dominio

1. He creado un archivo YAML en .github/workflows/ con nombre descriptivo.
2. He definido correctamente el evento on para que se active en push a main.
3. He incluido al menos un job con runs-on especificando un runner como ubuntu-latest.
4. He añadido steps que usan actions/checkout@v4 y comandos run básicos.
5. He probado el workflow haciendo un push a mi repositorio y verificado la ejecución en la pestaña Actions.
6. He revisado la indentación YAML para evitar errores de sintaxis.
7. He actualizado el workflow para incluir un paso de instalación de dependencias relevantes a mi proyecto.

Configura un workflow de CI para una aplicación Node.js

Sigue estos pasos para crear y probar un workflow YAML que automatice la construcción y pruebas de una aplicación Node.js:

1. Crea un repositorio en GitHub (o usa uno existente) con un proyecto Node.js simple que incluya un archivo package.json y un script de test (ej., npm test que ejecute un test básico).
2. En tu máquina local, clona el repositorio y crea la carpeta .github/workflows/ en la raíz del proyecto.
3. Dentro de esa carpeta, crea un archivo llamado node-ci.yml y copia el segundo ejemplo de código de la lección, ajustando el nombre y eventos si es necesario.
4. Haz commit y push de los cambios a la rama main. Ve a la pestaña Actions en tu repositorio GitHub para ver el workflow en ejecución.
5. Verifica que todos los steps pasen correctamente, especialmente la instalación de dependencias y la ejecución de tests. Si hay fallos, revisa los logs para identificar errores comunes como problemas de sintaxis YAML o comandos incorrectos.
6. Opcional: Modifica el workflow para que también se ejecute en pull requests a la rama main, añadiendo el evento correspondiente en la sección on.

• Asegúrate de que tu archivo package.json tenga un script test definido, aunque sea un echo simple, para que npm test no falle.
• Si el workflow falla en el paso de checkout, verifica que el repositorio sea público o que tengas los permisos adecuados si es privado.
• Usa la acción actions/setup-node@v4 con node-version: '18' para garantizar compatibilidad; puedes cambiarlo a otra versión si tu proyecto lo requiere.

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.