Módulo 1: Why Cicd And Gitops

6. Manos a la obra: instalando `act`

Siguiente →

Descripción

Esta es la primera lección de la guía donde vas a ejecutar comandos de verdad. Vas a instalar act en tu máquina, confirmar la instalación con act --version, verificar que Docker está corriendo (la dependencia sin la cual act no puede hacer nada), y pinear la imagen del runner en un archivo .actrc — para que cada corrida de esta guía use exactamente la misma imagen, sin sorpresas. Cada bloque Qué esperar de esta lección indica explícitamente si la salida es literal (ejecutada para escribir esta lección, hoy) o representativa — nunca vas a encontrar un número inventado sin esa etiqueta.

Conexión con el módulo

Las lecciones 1 a 5 te dieron todo el porqué: el problema del apply manual, el vocabulario de CI/CD, GitOps, y por qué esta guía elige GitHub Actions. Esta lección, y la que sigue, te dan el cómo. Terminas esta lección con act funcionando en tu máquina, conectado a Docker — la lección 7 lo usa, por primera vez, sobre un workflow real.

Analogía: un simulador de vuelo para el pipeline

Antes de instalar nada, vale la pena que entiendas qué es exactamente act, con una imagen concreta. Un simulador de vuelo no es "casi un avión" — es el mismo software de control, las mismas respuestas físicas modeladas, las mismas maniobras que un piloto ejecutaría en el aire real, corridas en un cuarto sin ventanas, sin subirse a ningún avión de verdad. act es eso para un workflow de GitHub Actions: corre el mismo YAML, con las mismas Actions reales del Marketplace, dentro de contenedores Docker pensados para imitar lo más fielmente posible un runner real de GitHub — sin que ese YAML toque nunca un servidor de GitHub. Cuando termines de practicar en el simulador, el manual de vuelo no cambia una sola página para el avión real.

Paso 1 — Instalar act

Esta guía usa act 0.2.89, publicada el 1 de junio de 2026 — la versión estable disponible al escribir esta guía. Elige el método que corresponda a tu situación.

macOS/Linux, vía Homebrew (el método de esta guía)

act está disponible directamente en el repositorio principal de Homebrew (homebrew-core), sin necesitar un tap aparte:

brew install act

Qué esperar (salida literal, ejecutada para escribir esta lección):

==> Fetching downloads for: act
✔︎ Bottle act (0.2.89)
==> Would install 1 formula:
act
🍺  /opt/homebrew/Cellar/act/0.2.89: 10 files, 29.6MB
==> Running `brew cleanup act`...
Disable this behaviour by setting `HOMEBREW_NO_INSTALL_CLEANUP=1`.
Hide these hints with `HOMEBREW_NO_ENV_HINTS=1` (see `man brew`).
==> Caveats
zsh completions have been installed to:
  /opt/homebrew/share/zsh/site-functions

act es un único binario, sin dependencias adicionales que instalar aparte de Docker (que verificas en el Paso 2) — no necesita, a diferencia de Terraform, ningún registro de providers ni configuración adicional para funcionar.

Alternativa: la extensión oficial de GitHub CLI

Si ya tienes gh (GitHub CLI) instalado, existe una extensión oficial mantenida por el propio autor de act que lo instala como subcomando de gh:

gh extension install https://github.com/nektos/gh-act

Esta guía no ejecuta este camino —brew install act ya cubre la instalación—, pero es una alternativa real y documentada si tu flujo de trabajo ya vive dentro de gh. El resultado final es el mismo binario de act, invocado como gh act en vez de act a secas.

Paso 2 — Confirmar la instalación y verificar Docker

act --version

Qué esperar (salida literal, ejecutada en este momento para escribir esta lección):

act version 0.2.89

Si tu terminal responde con command not found: act, el binario no quedó en tu PATH — revisa "Errores comunes" al final de esta lección.

act no hace nada por sí solo: cada job que corre es, por dentro, un contenedor Docker. Antes de seguir, confirma que Docker está corriendo (no solo instalado):

docker ps

Qué esperar (una tabla vacía, con solo los encabezados, es la respuesta correcta si no tienes ningún contenedor corriendo todavía):

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Si este comando falla con un error de conexión al daemon de Docker, abre Docker Desktop (o arranca el servicio de Docker) antes de seguir — sin Docker corriendo, ningún comando de act de esta guía va a funcionar, sin excepción.

Paso 3 — Elegir y pinear la imagen del runner

Este es el paso que marca la diferencia entre una corrida reproducible y una que depende de qué imagen resuelva act el día que la corras. La primera vez que ejecutas cualquier comando de act sin haberle indicado una imagen explícitamente, te pregunta cuál usar:

Qué esperar (salida literal, capturada en la primera corrida real de act en esta máquina, antes de crear .actrc):

? Please choose the default image you want to use with act:
  - Large size image: ca. 17GB download + 53.1GB storage, you will need 75GB of free disk space, snapshots of GitHub Hosted Runners without snap and pulled docker images
  - Medium size image: ~500MB, includes only necessary tools to bootstrap actions and aims to be compatible with most actions
  - Micro size image: <200MB, contains only NodeJS required to bootstrap actions, doesn't work with all actions

Tres tamaños, tres compromisos distintos entre fidelidad y peso de descarga:

  • Large (~17GB de descarga, ~53GB en disco): una réplica casi completa de lo que trae un runner real hospedado por GitHub — la mayoría de las herramientas preinstaladas que encontrarías en ubuntu-latest real. Pesada, pero la más fiel.
  • Medium (~500MB): solo lo necesario para arrancar Actions, compatible con la mayoría de los casos reales — la que usa esta guía.
  • Micro (<200MB): solo Node.js, lo mínimo para que las Actions basadas en JavaScript arranquen — no funciona con Actions que asumen otras herramientas preinstaladas (como hashicorp/setup-terraform, que vas a usar desde el Módulo 3).

Esta guía elige Medium: suficientemente completa para todo lo que vas a construir (incluida la instalación explícita de Terraform con hashicorp/setup-terraform@v3 en cada corrida, en vez de asumirlo preinstalado), sin el costo de descarga de la imagen Large.

En vez de responder ese prompt interactivo cada vez —lo que además rompería la reproducibilidad de esta guía si act cambiara su comportamiento por defecto en el futuro—, fija la elección explícitamente en un archivo .actrc, en la raíz de tu proyecto:

-P ubuntu-latest=catthehacker/ubuntu:act-latest

Esta única línea le dice a act, sin ambigüedad, qué imagen Docker usar cada vez que un workflow declare runs-on: ubuntu-latest — la etiqueta catthehacker/ubuntu:act-latest es, específicamente, la variante medium mantenida por la comunidad de act para este propósito exacto.

Con .actrc en su lugar, confirma que act reconoce la configuración sin volver a preguntar:

act -l

Qué esperar (salida literal, sin ningún workflow todavía en esta carpeta — solo el encabezado de la tabla, y sin el prompt interactivo del paso anterior):

Stage  Job ID  Job name  Workflow name  Workflow file  Events

Sin errores, sin preguntas — exactamente el comportamiento que vas a necesitar cada vez que corras act en andes-cargo-infra/ desde la lección 8 en adelante.

Errores comunes

command not found: act después de brew install (de flujo). Qué pasa: el comando terminó sin errores, pero tu shell no encuentra el binario. Por qué pasa: en macOS, si Homebrew no está enlazado correctamente al PATH de tu shell (más común en instalaciones recientes de Homebrew o en shells no estándar), el binario existe en /opt/homebrew/bin/ pero tu terminal no lo busca ahí. Cómo detectarlo: which act no devuelve ninguna ruta. Cómo corregirlo: cierra y vuelve a abrir tu terminal; si persiste, confirma con brew --prefix act la ruta de instalación y agrégala a tu PATH manualmente, o corre brew link act.

Advertencia de arquitectura en Apple Silicon (reproducida, literal, para esta lección). Qué pasa: en una Mac con chip M-series (M1/M2/M3/M4), cada corrida de act imprime esta advertencia antes de arrancar cualquier job:

level=warning msg= ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠

Por qué pasa: las imágenes de runner de act (como catthehacker/ubuntu:act-latest) están construidas mayoritariamente para arquitectura amd64 (Intel/AMD), y Docker en Apple Silicon las corre por emulación. Cómo detectarlo: el mensaje aparece, literal, en la salida de cada act push/act -l en una Mac con chip Apple Silicon — no es un error, es una advertencia informativa. Cómo corregirlo: en la inmensa mayoría de los workflows de esta guía no hace falta actuar sobre ella —la emulación funciona correctamente, solo un poco más lenta—; si algún día una Action específica falla de forma rara solo en Apple Silicon, agrega --container-architecture linux/amd64 al comando de act como indica el propio mensaje.

El prompt interactivo vuelve a aparecer aunque ya creaste .actrc (de ubicación). Qué pasa: alguien crea .actrc en una carpeta, pero corre act desde otra carpeta distinta, y el prompt de elección de imagen reaparece. Por qué pasa: act busca .actrc en el directorio de trabajo actual (y en el $HOME del usuario como configuración global) — un .actrc en ~/proyecto-a/ no aplica si corres act desde ~/proyecto-b/. Cómo detectarlo: el prompt de "Please choose the default image" reaparece en una carpeta donde ya creíste haberlo resuelto. Cómo corregirlo: confirma con pwd en qué carpeta estás parado, y que .actrc exista ahí mismo (ls -la .actrc). Cada proyecto de esta guía —el laboratorio de la lección 7, y después andes-cargo-infra/ desde la lección 8— necesita su propio .actrc.

Ejercicios

Ejercicio 1 — Verifica tu propia instalación. Corre act --version y docker ps en tu máquina, ahora mismo. ¿Coinciden con la salida literal de esta lección? Si act --version muestra un número distinto a 0.2.89, ¿qué te dice eso sobre cuándo instalaste?

Ver solución

act --version debería mostrar act version 0.2.89 o una versión posterior —Homebrew instala la última disponible al momento de tu brew install, así que un número mayor es normal y esperable si instalaste después de que se publicara esta guía; un número menor indicaría una instalación vieja en caché, que valdría la pena actualizar con brew upgrade act. docker ps, si no tienes ningún contenedor corriendo, debería mostrar únicamente la fila de encabezados, sin ninguna fila de datos debajo.

Ejercicio 2 — Explica el tamaño de imagen a un colega. Un compañero te pregunta por qué esta guía eligió la imagen "Medium" en vez de la "Large", si la "Large" es "más completa y se parece más a un runner real". Respóndele en dos o tres frases.

Ver solución

Una respuesta completa suena, más o menos, así: "La imagen Large es, sí, la más fiel a un runner real de GitHub, pero pesa cerca de 17GB de descarga y hasta 53GB en disco — un costo alto solo para practicar localmente. La imagen Medium (~500MB) trae lo necesario para que la gran mayoría de las Actions reales funcionen, incluida hashicorp/setup-terraform, que instala Terraform explícitamente en cada corrida en vez de asumirlo preinstalado — así que no perdemos fidelidad en lo que esta guía necesita, solo en herramientas que nunca vamos a usar."

Ejercicio 3 — Diagnostica el prompt que reaparece. Un colega te dice: "creé mi .actrc ayer, pero hoy act me volvió a preguntar qué imagen quiero usar". ¿Cuál es la primera pregunta que le harías, según lo que aprendiste en "Errores comunes"?

Ver solución

La primera pregunta debería ser: "¿estás corriendo act desde la misma carpeta donde creaste el .actrc?". act busca ese archivo en el directorio de trabajo actual — si tu colega creó .actrc dentro de un proyecto pero después corrió act desde otra carpeta (por ejemplo, un nuevo proyecto de prueba, o andes-cargo-infra/ en vez del laboratorio de la lección 7), el archivo simplemente no está donde act lo busca, y el comportamiento por defecto (preguntar) vuelve a aparecer.

Resumen y siguiente paso

En esta lección instalaste act 0.2.89 con Homebrew y confirmaste la instalación con act --version (salida literal, ejecutada hoy). Verificaste que Docker está corriendo con docker ps, viste el prompt real que act muestra la primera vez que elige una imagen de runner, y lo resolviste de forma permanente y reproducible con un archivo .actrc que pinea catthehacker/ubuntu:act-latest — la imagen medium que vas a usar en toda esta guía.

Antes de avanzar deberías poder: instalar act desde cero en tu sistema, sin mirar esta lección; explicar la diferencia entre las imágenes Large, Medium y Micro; y crear un .actrc que evite el prompt interactivo en cualquier proyecto nuevo.

Tienes la herramienta instalada y Docker verificado, pero todavía no corriste ningún workflow real. La lección 7 hace exactamente eso: tu primer "hola mundo" de punta a punta.

Recursos

  1. nektosact.com — Installation — todos los métodos de instalación documentados oficialmente, incluida la extensión de gh.
  2. nektosact.com — Runners — documentación oficial de las imágenes Large/Medium/Micro y cómo pinearlas con .actrc.
  3. GitHub — nektos/act — el repositorio oficial de la herramienta.
  4. Homebrew — Formula: act — la página del formula en el repositorio principal de Homebrew.
← Anterior5. GitHub Actions y sus alternativas, con honestidad de mercadoSiguiente →7. Manos a la obra: tu primer workflow local, de punta a punta