Cómo ejecutar GitHub Actions y GitLab CI localmente antes de enviar

Puede ejecutar GitHub Actions en su propia computadora con `act` y GitLab CI con gitlab-ci-local: ambos leen el archivo de canalización e inician cada trabajo en un contenedor Docker. Instale Docker, instale el ejecutor y luego ejecute act -j test o gitlab-ci-local test desde la carpeta del repositorio. Un trabajo fallido ahora falla en segundos en su máquina en lugar de después de un impulso y una espera por un ejecutor alojado.

Esta guía cubre qué instalar en macOS, Windows y Linux, los comandos para ambos ejecutores, un flujo de trabajo de muestra que puede copiar, los límites de las ejecuciones locales y los errores que las personas encuentran primero. El tutorial utiliza GitTree, el cliente Git que creamos: su página Canalizaciones locales comprueba lo que ha instalado, escribe un archivo de muestra y prepara el comando exacto para usted. Los canales locales son parte del plan gratuito de GitTree y no necesitan una cuenta de hosting.

¿Por qué ejecutar canalizaciones de CI localmente?

Cada cambio en un archivo de flujo de trabajo es código que no puede probar hasta que se ejecute. Sin un corredor local, el ciclo es: editar el YAML, confirmar, enviar, esperar un corredor, leer el registro, repetir. Cada ronda cuesta minutos y deja un rastro de confirmaciones como "inténtalo de nuevo". Una ejecución local acorta el ciclo a segundos y mantiene limpio el historial.

Lo que necesitas: Docker más un corredor

Ambos ejecutores inician cada trabajo en un contenedor, por lo que se debe instalar y ejecutar un motor Docker: Docker Desktop, OrbStack o Colima en macOS, Docker Desktop en Windows, Docker Engine o Docker Desktop en Linux. Luego instale el corredor para su archivo.

gitlab-ci-local necesita Node.js 18 o posterior cuando lo instala con npm. Verifique la configuración con docker info, act --version y gitlab-ci-local --version: si docker info falla, arranque el motor antes que nada.

Ejecute GitHub Actions localmente con act

Ejecute act desde la carpeta raíz del repositorio. Primero enumere los trabajos y luego ejecute el que está trabajando. De forma predeterminada, act simula un evento push, por lo que los trabajos que solo se ejecutan en otros eventos necesitan el nombre del evento.

# list workflows and jobs
act -l

# run one job from one workflow file
act -W .github/workflows/ci.yml -j test

# simulate a pull request instead of a push
act pull_request -j test

# pass a secret the job needs
act -j deploy -s NPM_TOKEN="$NPM_TOKEN"

# Apple silicon: run x86_64 images
act -j test --container-architecture linux/amd64

La primera ejecución pregunta qué imagen de corredor usar. Medio se adapta a la mayoría de los proyectos; las imágenes pequeñas omiten las herramientas que incluyen los corredores alojados y la imagen completa es muy grande. Si un paso falla con "comando no encontrado", elija una imagen más grande con -P ubuntu-latest=<image> o instale la herramienta en un paso.

Ejecute GitLab CI localmente con gitlab-ci-local

gitlab-ci-local lee .gitlab-ci.yml de la carpeta actual. Sin argumentos, recorre todo el proceso; asígnele un nombre de trabajo para ejecutar un trabajo. --list muestra los trabajos sin ejecutarlos, una forma rápida de comprobar que YAML analiza.

# list jobs and stages
gitlab-ci-local --list

# run one job
gitlab-ci-local test

# pass a CI/CD variable
gitlab-ci-local test --variable API_URL=http://localhost:8080

Un flujo de trabajo de muestra para comenzar

Esta es la forma del ejemplo GitHub Actions de GitTree: dos trabajos, compilados y luego probados, que funcionan igual con act y en GitHub. Reemplace los comandos con los suyos propios.

name: GitTree local check

on:
  push:
  pull_request:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: npm ci && npm run build

  test:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v4
      - name: Test
        run: npm test

En qué se diferencia una ejecución local de una CI alojada

• Los secretos y las variables configurados en GitHub o GitLab no están disponibles; pasar los que necesita un trabajo.
• Contenedores, no máquinas virtuales: los servicios que necesitan systemd, o una máquina virtual completa, no se ejecutan de la misma manera.
• Las imágenes difieren de los corredores alojados; una herramienta faltante es un paquete faltante, no un flujo de trabajo roto.
• Los eventos son simulados: act por defecto es push; Los flujos de trabajo, inclusiones y plantillas reutilizables los resuelve el ejecutor, no el editor.
• Una ejecución local que pasa no es un resultado alojado: acorta el ciclo; su anfitrión todavía tiene la última palabra.

Errores y correcciones comunes

Antes de presionar: predice conflictos, busca secretos, obtén una vista previa del impulso

Una ejecución de oleoducto local responde a una pregunta: ¿se aprobarán los trabajos? Otras tres comprobaciones detectan lo que CI informa tarde o no informa, y ​​cada una de ellas también se ejecuta en su computadora antes de enviar algo.

1. Predecir la fusión. git merge-tree --write-tree --name-only HEAD origin/main fusiona en la memoria y enumera los archivos que entrarían en conflicto, sin tocar su árbol de trabajo. GitTree realiza el mismo tipo de verificación y advierte antes de una fusión que pueda entrar en conflicto; consulte cómo resolver conflictos de fusión de Git.
2. Compruebe si hay secretos. Antes de una confirmación o un envío, GitTree escanea el cambio localmente en busca de posibles tokens, contraseñas y claves privadas y se detiene con un cuadro de diálogo si encuentra uno. Un secreto que llega al mando hay que girarlo, por lo que el momento más barato para coger uno es antes del push. Una advertencia no es una garantía, así que revisa lo que envías.
3. Vista previa del envío. La vista previa del envío enumera las confirmaciones y los archivos que el envío enviaría y, para cada archivo de flujo de trabajo que puede leer, si una canalización se ejecutará, puede ejecutarse o no se ejecutará en este envío, con el motivo.

Luego ejecute el trabajo localmente y presione una vez. La guía de advertencias secretas y la guía de vista previa del envío cubren ambos cuadros de diálogo en detalle.

¿Qué pasa con Bitbucket Pipelines y Azure Pipelines?

No hay ningún corredor local mantenido para bitbucket-pipelines.yml o azure-pipelines.yml que coincida con act o gitlab-ci-local. Un enfoque práctico es mantener los comandos de compilación y prueba en scripts, llamarlos desde su canal alojado y agregar un pequeño archivo GitHub Actions o GitLab CI solo para ejecuciones locales. GitTree marca esos archivos como Sin corredor local y ofrece muestras exactamente para esto.

Próximos pasos: la Guía de ejecución de canalizaciones localmente documenta cada botón, Ejecuciones de CI/CD cubre ejecuciones hospedadas, reejecuciones y aprobaciones, y el Lanzador de herramientas enumera las otras herramientas integradas de GitTree.