Cómo ejecutar tus acciones de GitHub localmente con Act

Las acciones de GitHub han revolucionado la forma en que los desarrolladores automatizan flujos de trabajo dentro de sus repositorios. Desde pipelines de integración continua y despliegue continuo (CI/CD) hasta la automatización de etiquetado de problemas y generación de notas de lanzamiento, las acciones proporcionan una forma poderosa e integrada de gestionar el ciclo de vida del desarrollo de software directamente dentro de GitHub.

No obstante, desarrollar y probar estos flujos de trabajo puede sentirse a veces tedioso. El ciclo tradicional implica:

Realizar cambios en tus archivos de flujo de trabajo (típicamente ubicados en .github/workflows/).
Confirmar estos cambios.
Subirlos a tu repositorio de GitHub.
Esperar a que los runners de GitHub recojan el trabajo y lo ejecuten.
Analizar los registros en el sitio web de GitHub para ver si tus cambios funcionaron o si introdujeron errores.

Este proceso, especialmente la parte de espera y el cambio de contexto entre tu editor local y la interfaz de GitHub, puede ralentizar significativamente el desarrollo, particularmente al iterar en flujos de trabajo complejos o depurar problemas difíciles. ¿Y si pudieras probar tus acciones antes de subirlas?

Precisamente aquí es donde entra act. Como su lema sugiere, "Piensa globalmente, act localmente". act es una herramienta de línea de comandos de código abierto diseñada para ejecutar tus flujos de trabajo de acciones de GitHub localmente utilizando contenedores de Docker. Simula el entorno proporcionado por las acciones de GitHub, permitiéndote probar e iterar sobre tus flujos de trabajo rápidamente sin la necesidad de confirmar y subir cada cambio menor.

💡

¿Quieres una gran herramienta de prueba de API que genere hermosa documentación de API?

¿Quieres una plataforma integrada, todo en uno, para que tu equipo de desarrollo trabaje juntos con máxima productividad?

Apidog satisface todas tus demandas y reemplaza a Postman a un precio mucho más asequible!

button

¿Por qué ejecutar acciones de GitHub localmente con `act`?

Los beneficios de incorporar act en tu flujo de trabajo de desarrollo son sustanciales:

Retroalimentación rápida: Esta es la principal ventaja. En lugar del ciclo de confirmar-subir-esperar-depurar, puedes ejecutar tu flujo de trabajo inmediatamente después de realizar un cambio localmente. Obtén retroalimentación en segundos o minutos, no en minutos o decenas de minutos. Esto acelera drásticamente el proceso de desarrollo y depuración para tus archivos de .github/workflows/.
Ejecutor de tareas local: Muchos proyectos utilizan herramientas como make, scripts de npm, o scripts de shell personalizados para definir tareas comunes de desarrollo (compilación, prueba, linting, etc.). act te permite consolidar estas tareas. Puedes definir tu proceso de compilación, prueba y otros como trabajos de acciones de GitHub, y luego usar act para ejecutar estos mismos trabajos localmente con fines de desarrollo. Esto reduce la duplicación y asegura consistencia entre tu entorno de desarrollo local y tu pipeline de CI/CD. Definís las tareas una vez en tus archivos de flujo de trabajo, y se ejecutan de manera idéntica (o muy similar) en todas partes.
Desarrollo sin conexión: Prueba la sintaxis y la lógica básica del flujo de trabajo incluso sin una conexión a internet constante (aunque las descargas iniciales de imágenes y ciertas acciones pueden requerir conectividad).
Ahorro de costos: Si bien GitHub ofrece un generoso nivel gratuito para repositorios públicos y precios razonables para privados, ejecutar flujos de trabajo complejos o largos repetidamente durante el desarrollo puede consumir minutos de runner. Probar localmente evita este uso.
Poder de depuración: La depuración de acciones fallidas en GitHub a menudo implica agregar registros adicionales, subir y esperar. Con act, puedes inspeccionar el entorno local, montar volúmenes y potencialmente usar técnicas de depuración más avanzadas dentro de los contenedores de Docker que se inician.

¿Cómo funciona `act`?

Entender el mecanismo detrás de act ayuda a usarlo de manera efectiva y a solucionar problemas potenciales. Aquí hay un desglose de su funcionamiento:

Análisis de flujo de trabajo: Cuando ejecutas el comando act en el directorio raíz de tu repositorio, escanea el directorio .github/workflows/ en busca de tus archivos YAML de flujo de trabajo.
Simulación de desencadenamiento de eventos: Por defecto, act simula un evento de push, pero puedes especificar otros eventos como pull_request, workflow_dispatch, etc. Determina qué flujos de trabajo y trabajos deben ejecutarse según el evento especificado y los desencadenadores on: definidos en tus archivos de flujo de trabajo.
Análisis de dependencias: act analiza las dependencias entre trabajos dentro de un flujo de trabajo (usando la palabra clave needs:) para determinar el orden de ejecución correcto.
Gestión de imágenes de Docker: Para cada trabajo, act identifica el entorno del runner especificado (por ejemplo, runs-on: ubuntu-latest). Luego, mapea esto a una imagen de Docker específica. act utiliza la API de Docker para:

Descargar imágenes: Descargar las imágenes de runner requeridas y cualquier imagen de Docker utilizada por acciones en contenedores (uses: docker://...). Por defecto, descarga imágenes en cada ejecución a menos que se configure de otra manera.
Construir imágenes (si es necesario): Si una acción apunta a un Dockerfile local (uses: ./path/to/action), act puede construir la imagen de Docker localmente.

Ejecución de contenedores: act utiliza la API de Docker para crear y ejecutar contenedores para cada paso dentro de un trabajo. Configura estos contenedores para imitar el entorno de acciones de GitHub lo más cerca posible:

Variables de entorno: Se inyectan variables de entorno estándar de acciones de GitHub (como GITHUB_SHA, GITHUB_REF, GITHUB_REPOSITORY, CI, etc.).
Sistema de archivos: El código del repositorio se monta en el directorio de trabajo del contenedor (/github/workspace). Los archivos generados por los pasos se persisten dentro del contenedor para pasos posteriores.
Redes: Los contenedores se ejecutan típicamente en una red de puente de Docker, permitiendo la comunicación si es necesario (aunque los detalles de la red pueden diferir del entorno de GitHub).

Transmisión de registros: act transmite los registros de los contenedores en ejecución directamente a tu terminal, proporcionando retroalimentación en tiempo real sobre el progreso de la ejecución y cualquier error.

Esencialmente, act orquesta contenedores locales de Docker para replicar el flujo de ejecución y el entorno de tus flujos de trabajo de acciones de GitHub.

Requisitos previos: Instalación de Docker

La dependencia principal para act es Docker. act aprovecha el motor de Docker para crear los entornos aislados necesarios para ejecutar los pasos de tu flujo de trabajo. Antes de instalar act, debes tener una instalación de Docker funcional en tu sistema.

Instalar Docker: Sigue las instrucciones oficiales para tu sistema operativo:
macOS: Docker Desktop para Mac
Windows: Docker Desktop para Windows (Requiere WSL 2 o Hyper-V)
Linux: Sigue las instrucciones específicas para tu distribución (por ejemplo, Ubuntu, Fedora, Debian, etc.). Asegúrate de agregar tu usuario al grupo docker para ejecutar comandos de Docker sin sudo.
Verificar Docker: Después de la instalación, abre tu terminal y ejecuta docker run hello-world. Este comando descarga una pequeña imagen de prueba y la ejecuta en un contenedor. Si se ejecuta con éxito, tu configuración de Docker está lista.

Instalando `act`

Una vez que Docker esté en funcionamiento, puedes instalar act. Hay varias formas de hacerlo, dependiendo de tu sistema operativo y preferencias.

1. Homebrew (macOS y Linux)

Si utilizas el gestor de paquetes Homebrew, la instalación es sencilla:

brew install act

Esto instala la última versión estable. Si deseas la versión de desarrollo más reciente (que podría requerir un compilador), puedes usar:

brew install act --HEAD

2. Extensión de CLI de GitHub (macOS, Windows, Linux)

Si ya utilizas la CLI de GitHub (gh), puedes instalar act como una extensión:

gh extension install nektos/gh-act

Después de la instalación, invocas act a través del comando gh:

gh act          # En lugar de solo 'act'
gh act -l
gh act pull_request

3. Chocolatey (Windows)

Para los usuarios del gestor de paquetes Chocolatey en Windows:

choco install act-cli

(Nota: Algunas fuentes pueden listar act en lugar de act-cli. Verifica el nombre del paquete más reciente en el repositorio comunitario de Chocolatey si encuentras problemas).

4. Scoop (Windows)

Para los usuarios del gestor de paquetes Scoop en Windows:

scoop install act

5. WinGet (Windows)

Para los usuarios del Gestor de Paquetes de Windows (winget):

winget install nektos.act

6. Instalador de Script para Linux

Un script de conveniencia está disponible para distribuciones de Linux sin fácil acceso a través de gestores de paquetes:

curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

(Nota: Siempre ten cuidado al canalizar scripts directamente a sudo. Revisa el contenido del script primero si tienes preocupaciones de seguridad).

7. Otros Métodos (Arch, COPR, MacPorts, Nix)

Instrucciones de instalación para otros gestores de paquetes como pacman (Arch), COPR (Fedora), MacPorts y Nix están disponibles en la documentación oficial de act:

Verificación:

Después de la instalación, abre una nueva ventana de terminal y ejecuta:

act --version
# o si usas la extensión gh:
gh act --version

Esto debería imprimir la versión instalada de act, confirmando que la instalación fue exitosa.

Configuración inicial: Imágenes del runner

La primera vez que ejecutas act dentro de un directorio de proyecto, puede que te pida que elijas un tamaño de imagen de runner predeterminado. Las acciones de GitHub ofrecen runners con diferentes recursos y software preinstalado. act intenta imitar esto utilizando diferentes imágenes base de Docker.

Normalmente se te presentará una elección como esta:

? Por favor, elige la imagen predeterminada que deseas usar con act:

  - Micro: Imagen mínima con soporte para nodejs (~200MB) docker.io/node:16-buster-slim
  - Medium: Imagen de Act con herramientas básicas (~500MB) ghcr.io/catthehacker/ubuntu:act-latest
  - Large: Imagen de runner de acciones de Github (~17GB) ghcr.io/catthehacker/ubuntu:full-latest

¿Imagen predeterminada? [Medium]:

Micro: Basada en imágenes slim oficiales de Node.js (como node:16-buster-slim o node:16-bullseye-slim). Muy pequeña y rápida de descargar, pero contiene solo Node.js y bibliotecas de sistema mínimas. Adecuada si tus acciones solo necesitan Node.js o instalan todas sus dependencias por sí mismas.
Medium: Proporcionada por el usuario catthehacker (por ejemplo, catthehacker/ubuntu:act-latest, catthehacker/ubuntu:act-22.04). Estas imágenes incluyen herramientas más comunes encontradas en los runners de GitHub pero aún son relativamente ligeras (alrededor de 500MB). Esta es a menudo la predeterminada recomendada ya que equilibra características y tamaño.
Large: También de catthehacker (por ejemplo, catthehacker/ubuntu:full-latest, catthehacker/ubuntu:full-22.04). Estas se crean a partir de volcado de sistema de archivos de los runners alojados en GitHub y contienen casi todo el software preinstalado. Ofrecen la mayor compatibilidad pero son muy grandes (a menudo >17GB), lo que lleva a largos tiempos de descarga inicial y un uso significativo de espacio en disco.

Recomendación: Comienza con la imagen Medium. Proporciona un buen equilibrio y funciona para muchos casos de uso comunes. Si encuentras problemas debido a software faltante, puedes instalar el software dentro de los pasos de tu flujo de trabajo o cambiar a usar la imagen Large para ese runner específico (más sobre esto más adelante).

act guarda tu elección en un archivo de configuración (~/.actrc). Puedes cambiar la predeterminada más tarde editando este archivo o volviendo a ejecutar act en un directorio donde necesite configurarse.

Uso básico de `act`: Ejecutar tus flujos de trabajo

Una vez instalado y configurado, usar act es relativamente simple. Navega al directorio raíz de tu proyecto (el que contiene la carpeta .github) en tu terminal.

1. Ejecutar evento predeterminado (push)

El comando más simple ejecuta los flujos de trabajo desencadenados por el evento predeterminado push:

act
# o
gh act

act analizará tus flujos de trabajo, identificará los trabajos desencadenados on: push, descargará las imágenes de Docker necesarias (si no están ya en caché) y ejecutará los trabajos.

2. Listar flujos de trabajo y trabajos disponibles

Para ver qué flujos de trabajo y trabajos act reconoce y ejecutaría para el evento predeterminado:

act -l
# o
gh act -l

Esto produce una lista como:

Etapa  ID del trabajo    Nombre del trabajo      Nombre del flujo de trabajo  Archivo del flujo de trabajo  Eventos
0      build             Compilar             Pipeline CI            ci.yaml                  push
1      test              Probar               Pipeline CI            ci.yaml                  push
1      lint              Lint                Calidad de Código      codeql.yaml              push,pull_request

3. Ejecutar un trabajo específico

Si solo deseas probar un único trabajo de un flujo de trabajo, usa la bandera -j seguida del ID del trabajo (del resultado de act -l):

act -j build
# o
gh act -j build

4. Desencadenar un evento específico

Los flujos de trabajo a menudo se desencadenan por eventos distintos a push. Puedes simular estos eventos proporcionando el nombre del evento como un argumento a act:

# Simular un evento de pull request
act pull_request

# Simular un evento de workflow_dispatch (desencadenamiento manual)
act workflow_dispatch

# Simular un evento de schedule
act schedule

# Simular un evento de release
act release -e event.json # Proporciona detalles de carga útil del evento si es necesario

act solo ejecutará flujos de trabajo y trabajos configurados para ejecutarse on: el evento especificado.

5. Pasar entradas para workflow_dispatch

Los flujos de trabajo desencadenados por workflow_dispatch pueden aceptar entradas. Puedes proporcionar estas usando la bandera --input o -i:

# Asumiendo que tu flujo de trabajo tiene una entrada llamada 'environment'
act workflow_dispatch --input environment=staging

6. Manejo de secretos

Los flujos de trabajo de acciones de GitHub a menudo dependen de secretos (como claves API o tokens). act no accede automáticamente a tus secretos de GitHub. Necesitas proporcionarlos localmente.

Indicador interactivo: Usa la bandera -s. act te pedirá que ingreses el valor para cada secreto definido en tu flujo de trabajo:

act -s MY_SECRET_TOKEN -s ANOTHER_SECRET

Alternativamente, solo act -s pedirá todos los secretos.

Variables de entorno: Los secretos a menudo se pasan como variables de entorno precedidas por SECRET_. Puedes definirlas en tu shell antes de ejecutar act:

export SECRET_MY_SECRET_TOKEN="your_value"
act

Archivo de secretos: Crea un archivo (por ejemplo, .secrets) con pares KEY=VALUE:

MY_SECRET_TOKEN=your_value
ANOTHER_SECRET=another_value

Luego ejecuta act con la bandera --secret-file:

act --secret-file .secrets

(¡Asegúrate de que este archivo esté agregado a tu .gitignore para evitar confirmar secretos!)

7. Manejo de variables y variables de entorno

Variables de flujo de trabajo: Puedes proporcionar valores para variables definidas a nivel de flujo de trabajo (vars: contexto, aunque el soporte completo del contexto vars en act puede ser limitado) usando la bandera --var o un --var-file, similar a los secretos.
Variables de entorno: Para establecer variables de entorno personalizadas para la ejecución del flujo de trabajo, usa la bandera --env o un --env-file.

act --env NODE_ENV=development --env CUSTOM_FLAG=true
act --env-file .env_vars

Gestión de entornos y imágenes del runner

Si bien las imágenes de runner predeterminadas (Micro, Medium, Large) cubren muchos escenarios, a menudo necesitas más control.

1. Limitaciones de imágenes predeterminadas

Recuerda que las imágenes de runner predeterminadas de act (especialmente Micro y Medium) no son idénticas a los entornos proporcionados por GitHub. Pueden carecer de herramientas específicas, bibliotecas o servicios del sistema (como systemd) que tu flujo de trabajo espera. Las imágenes Large ofrecen mayor fidelidad pero vienen con la desventaja de tamaño significativo.

2. Especificación de imágenes alternativas con -P

Si un trabajo requiere un entorno o conjunto de herramientas específico que no está presente en la imagen predeterminada, puedes indicarle a act que use una imagen de Docker diferente para una plataforma específica usando la bandera -P (plataforma).

El formato es -P <platform>=<docker-image>.

<platform>: La etiqueta utilizada en la directiva runs-on: de tu flujo de trabajo (por ejemplo, ubuntu-latest, ubuntu-22.04, ubuntu-20.04).
<docker-image>: El nombre completo de la imagen de Docker a utilizar (por ejemplo, node:18, python:3.10-slim, mcr.microsoft.com/devcontainers/base:ubuntu).

Ejemplos:

# Usa la imagen Large específicamente para trabajos que se ejecutan en ubuntu-22.04
act -P ubuntu-22.04=ghcr.io/catthehacker/ubuntu:full-22.04

# Usa una versión específica de Node.js para trabajos en ubuntu-latest
act -P ubuntu-latest=node:18-bullseye

# Usa una imagen más completa de nektos/act-environments (¡muy grande!)
# ADVERTENCIA: nektos/act-environments-ubuntu:18.04 es >18GB
act -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04

# Especifica múltiples plataformas si tu flujo de trabajo las usa
act -P ubuntu-20.04=node:16-buster -P ubuntu-22.04=node:18-bullseye

3. Uso de imágenes locales del runner (--pull=false)

Por defecto, act intenta descargar la última versión de la imagen de Docker especificada cada vez que se ejecuta. Si has construido una imagen de runner personalizada localmente o deseas asegurarte de que estás utilizando la versión exacta que tienes en caché, puedes deshabilitar este comportamiento:

act --pull=false
# o potencialmente usar modo sin conexión
act --action-offline-mode

Esto le indica a act que use la imagen disponible localmente si está presente y solo intente descargarla si falta.

4. Ejecutando nativamente en el host (-self-hosted)

Para flujos de trabajo que apuntan a macOS o Windows (runs-on: macos-latest o runs-on: windows-latest), si estás ejecutando act en ese mismo sistema operativo host, puedes indicarle a act que no use un contenedor de Docker para el propio runner. En su lugar, ejecutará los pasos directamente en tu máquina host. Esto puede ser útil si la compatibilidad con Docker es un problema o si necesitas acceso directo a los recursos del host.

# Ejecuta trabajos de macos-latest directamente en tu host Mac
act -P macos-latest=-self-hosted

# Ejecuta trabajos de windows-latest directamente en tu host Windows
act -P windows-latest=-self-hosted

Cuidado: Ejecutar directamente en el host elude el aislamiento proporcionado por Docker. Los pasos del flujo de trabajo tendrán acceso a tu sistema de archivos y potencialmente modificarán tu entorno host. Utiliza esta opción con precaución. Los pasos dentro del trabajo que utilicen explícitamente contenedores de Docker (como contenedores de servicio o acciones de contenedor) seguirán utilizando Docker.

Limitaciones y consideraciones

Si bien act es increíblemente útil, es importante ser consciente de sus limitaciones:

No es una réplica perfecta: act simula el entorno de acciones de GitHub pero no es idéntico. Existen diferencias en redes, servicios del sistema disponibles (por ejemplo, no hay systemd en contenedores de Docker fácilmente), recursos de hardware específicos y el conjunto exacto de herramientas preinstaladas (a menos que se utilicen las imágenes de runner muy grandes). Algunos flujos de trabajo, especialmente los complejos que interactúan mucho con el sistema operativo subyacente o características específicas de GitHub, pueden comportarse de manera diferente en act en comparación con GitHub.
Diferencias de contexto: Algunas partes del contexto github pueden estar incompletas o contener valores predeterminados/simulados cuando se ejecutan localmente. El contexto secrets siempre necesita entrada explícita. El soporte del contexto vars también puede tener limitaciones en comparación con el entorno en vivo de GitHub.
Concurrencia: act generalmente ejecuta trabajos secuencialmente en función de sus dependencias needs. No replica completamente la capacidad de GitHub para ejecutar trabajos independientes de manera concurrente utilizando estrategias de matriz a través de múltiples runners (aunque act admite la ejecución de trabajos de matriz, generalmente se ejecutan secuencialmente de manera local).
Servicios alojados: Características como el almacenamiento en caché (actions/cache) pueden funcionar de manera diferente o requerir configuración específica localmente en comparación con el servicio de caché integrado de GitHub. Los contenedores de servicio definidos en flujos de trabajo deberían funcionar, ya que act también utiliza Docker para esos.
Disponibilidad de plataformas: Solo puedes ejecutar trabajos basados en Linux dentro de Docker en cualquier host compatible con Docker (Mac, Windows, Linux). Para ejecutar trabajos de macos-latest, idealmente necesitas act en macOS (o usar la bandera -self-hosted en macOS). De manera similar, los trabajos de windows-latest típicamente requieren act en Windows (o -self-hosted en Windows). Si bien Docker puede ejecutar contenedores de Windows en Windows, el enfoque principal de act y el soporte más estable giran en torno a contenedores de Linux.

Recomendación: Usa act para desarrollo rápido, verificación de sintaxis, pruebas de lógica básica y iteración sobre trabajos o pasos individuales. Siempre realiza una validación final ejecutando tus flujos de trabajo en GitHub antes de fusionar cambios críticos, especialmente para pipelines de despliegue. Consulta la documentación oficial de act para la matriz de soporte detallada y los problemas conocidos.

Conclusión

Probar acciones de GitHub localmente es un gran impulsor de productividad, transformando el potencialmente lento y tedioso ciclo de depuración en un proceso rápido e iterativo. La herramienta CLI act proporciona una forma robusta y flexible de lograr esto aprovechando Docker para simular el entorno de runner de acciones de GitHub en tu máquina local.

Al integrar act en tu flujo de trabajo, obtienes:

Bucles de retroalimentación más rápidos.
Menor dependencia de subir a GitHub para pruebas.
La capacidad de usar tus definiciones de Acciones como un ejecutor de tareas local.
Mejoradas capacidades de depuración.

Si bien tiene limitaciones y no es un reemplazo perfecto 1:1 para el entorno en vivo de GitHub, act cubre una vasta gama de casos de uso y reduce significativamente la fricción involucrada en desarrollar flujos de trabajo de acciones de GitHub fiables y efectivos. Instálalo, intenta ejecutar tus flujos de trabajo existentes localmente y experimenta los beneficios de pensar globalmente mientras actúas localmente.

💡