Ir al contenido

Documentación Línea de comandos Línea de comandos

CI/CD

vmpal run ejecuta un trabajo de CI en un clon nuevo de una máquina virtual y después elimina el clon. Cada trabajo recibe una máquina limpia, como un runner de CI recién creado, pero en tu Mac y con tu propia configuración. Preparas la máquina virtual una sola vez, con las herramientas que necesitan tus compilaciones. Funciona con GitHub Actions, GitLab CI o cualquier runner de CI de tu Mac.

Pregúntale a tu agente de IA

Tu agente de programación puede configurarlo por ti. VMPal le da esta guía como vmpal help ci. Conéctalo a VMPal y pídele, por ejemplo:

  • “Configura un trabajo de GitHub Actions que ejecute mis pruebas en un clon nuevo de mi máquina virtual de Ubuntu.”
  • “Prepara una máquina virtual de Windows para CI con Visual Studio Build Tools.”
  • “Añade un trabajo de GitLab CI que compile esta app en mi máquina virtual de CI y guarde la compilación como artefacto.”

El resto de esta página explica cómo funciona, por si quieres saberlo.

Prepara una máquina virtual una vez

La máquina virtual maestra es aquella de la que parte cada trabajo, como una imagen base. Instala en ella lo que necesitan tus compilaciones, una sola vez:

vmpal create download:ubuntu --name "CI Ubuntu" --cpus 4 --memory 8 --wait
vmpal exec "CI Ubuntu" --admin -- apt-get update
vmpal exec "CI Ubuntu" --admin -- apt-get install -y build-essential git
vmpal stop "CI Ubuntu"
  • vmpal systems enumera lo que puedes instalar, como download:windows y download:macOS.
  • Una máquina virtual nueva comparte tu carpeta Descargas. Puede que macOS pida una vez permiso para que VMPal la use. Respóndelo antes de dejar el Mac ejecutando trabajos.

Mantén apagada la máquina virtual maestra, porque run la necesita así. Apágala con vmpal stop o con la opción Apagar de la máquina virtual. No basta con cerrar su ventana: eso guarda la máquina virtual en lugar de apagarla.

Para cambiarla más adelante, iníciala, haz los cambios y vuelve a apagarla.

La misma pantalla en cada trabajo

La pantalla de una máquina virtual sigue a su ventana, con el tamaño y la escala del monitor en el que se abre la ventana. Por eso, las pruebas de interfaz y las capturas de pantalla pueden variar de un trabajo a otro. Dale a la máquina virtual maestra una pantalla fija, y todos los clones tendrán la misma:

vmpal set "CI Ubuntu" --display 1440x900@2x

Eso son 1440 × 900 puntos a 2x, es decir, 2880 × 1800 píxeles. La pantalla mantiene ese tamaño en cualquier monitor, e incluso sin ninguna ventana. La ventana la muestra escalada para que quepa. Usa @1x para una pantalla sin escalado Retina. En una máquina virtual de Windows, 1x y 2x equivalen a un escalado del 100 % y del 200 %. --display window vuelve a seguir a la ventana.

Ejecuta un trabajo

vmpal run "CI Ubuntu" --isolated --copy-in .:src --copy-out src/out:./out -- /bin/sh -lc 'cd src && make test'

Esto copia la carpeta actual, como tu copia del repositorio, en src dentro de la máquina virtual. Ejecuta allí make test y después copia src/out de vuelta a ./out en tu Mac. Esto es lo que hace run, en orden:

  1. Clona la máquina virtual. La clonación es instantánea, porque el clon comparte el disco de la máquina virtual hasta que escribe en él.
  2. Inicia el clon y espera hasta que pueda ejecutar comandos.
  3. Copia dentro lo que indicaste con --copy-in.
  4. Ejecuta tu comando y muestra su salida a medida que llega.
  5. Copia fuera lo que indicaste con --copy-out, aunque el comando haya fallado.
  6. Apaga el clon y lo elimina definitivamente.

Imprime el nombre y el ID del clon en la salida de error estándar.

El código de salida decide si el trabajo pasa o falla, como en cualquier paso de CI. run termina con el código de salida de tu comando, así que el trabajo pasa o falla según tu comando. Dos códigos son propios de run:

Código de salida Significado
124 El comando superó el --timeout (2 horas de forma predeterminada)
125 El propio run no pudo hacer su parte. Por ejemplo, el clon no estuvo listo en 10 minutos

--isolated deja tu Mac fuera del clon. El clon no recibe nada de tu Mac salvo las copias. No tiene carpetas compartidas, puertos reenviados, portapapeles, arrastrar y soltar, altavoces ni micrófono, y solo usa la red compartida. Sin --isolated, el clon conserva lo que comparte la máquina virtual maestra, como tu carpeta Descargas, y cualquier trabajo podría leer y modificar esa carpeta. Si no, deja de compartirla en la máquina virtual maestra, una sola vez, con vmpal set "CI Ubuntu" --unshare Downloads.

Opción Qué hace
--copy-in <Mac path>:<VM path> Copia eso en el clon antes del comando, igual que cp. Se puede repetir
--copy-out <VM path>:<Mac path> Copia eso fuera después del comando, aunque haya fallado. Se puede repetir
--cwd, --admin, --timeout Funcionan igual que en exec. Las rutas de la máquina virtual son relativas a la carpeta de inicio del usuario. Con --admin, las copias también se hacen como administrador
--env NAME=value Define una variable de entorno para el comando. --env NAME pasa el valor de NAME en este Mac, para que un secreto no aparezca en la línea de comandos
--cpus <n>, --memory <GB> Definen las CPU y la memoria del clon
--name <name> Pone nombre al clon. El predeterminado es <VM> run <8 hex digits>
--isolated No le da al clon nada de tu Mac salvo las copias
--in-background Inicia el clon sin su ventana
--no-sign-in No inicia sesión en la pantalla de inicio de sesión del clon
--keep Conserva el clon para que puedas examinarlo. Elimínalo después con vmpal delete

Cancelación

Cuando se cancela un trabajo, el sistema de CI envía SIGINT o SIGTERM. Entonces, run detiene tu comando y elimina el clon. Una segunda señal hace que run termine al instante. En ese caso, imprime el nombre del clon y el comando que lo elimina.

Si quedó algún clon, vmpal list lo muestra. Elimínalo con vmpal delete <VM> --force --permanently.

Paso a paso

run ejecuta un solo comando. Para ejecutar varios comandos en un mismo clon, haz tú sus pasos. El clon no está aislado, así que funciona como run sin --isolated.

La línea trap elimina el clon termine como termine el paso: tanto si pasa como si falla, se cancela o lo detiene el -e del shell. El shell de GitHub se ejecuta con -e.

vm=$(vmpal clone "CI Ubuntu" --name "ci-$GITHUB_RUN_ID" --start --wait -q)
trap 'vmpal delete "$vm" --force --permanently' EXIT; trap 'exit 130' INT; trap 'exit 143' TERM
vmpal cp . "$vm:src"
vmpal exec "$vm" --cwd src -- make test || status=$?
vmpal cp "$vm:src/out" ./out
exit "${status:-0}"

GitHub Actions

Instala un runner autoalojado en el Mac. Un trabajo queda así:

jobs:
  test:
    runs-on: [self-hosted, macOS, ARM64]
    steps:
      - uses: actions/checkout@v7
      - run: exec vmpal run "CI Ubuntu" --isolated --copy-in .:src --copy-out src/out:./out -- /bin/sh -lc 'cd src && make test'
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: out
          path: out
  • exec hace que vmpal sea el propio proceso del paso. Así, cuando se cancela el trabajo, la señal llega a vmpal, y este elimina el clon.
  • if: always() sube out aunque fallen las pruebas.

GitLab CI

Instala GitLab Runner en el Mac, con el ejecutor shell. Un trabajo queda así:

test:
  script:
    - vmpal run "CI Ubuntu" --isolated --copy-in .:src --copy-out src/out:./out -- /bin/sh -lc 'cd src && make test'
  artifacts:
    when: always
    paths: [out/]

when: always conserva out aunque fallen las pruebas.

Para tener en cuenta

  • El runner. Instálalo en el Mac como LaunchAgent del usuario que tiene la sesión iniciada. Los runners de GitHub y de GitLab se instalan así. Evita que el Mac entre en reposo. vmpal abre VMPal en segundo plano. Los trabajos se ejecutan a la vez, cada uno en su propio clon, hasta donde lo permitan la memoria y las CPU.

  • Windows arranca en su pantalla de inicio de sesión. run inicia sesión con la contraseña que VMPal guarda para la máquina virtual. Si no hay ninguna contraseña guardada, espera a que alguien inicie sesión y desiste a los 10 minutos.

    • Si esa contraseña deja de funcionar, actualízala en la máquina virtual maestra, porque los clones la copian de ahí. Usa Ajustes › General › Cuenta › Actualizar contraseña… de la máquina virtual maestra, o vmpal set "CI Windows" --account-password-file <file>. Indica - como archivo para leer la contraseña de la entrada estándar.
    • Los comandos necesitan cmd.exe o powershell.exe. Se ejecutan con derechos estándar, salvo que indiques --admin.
    vmpal create download:windows --name "CI Windows" --wait
    vmpal stop "CI Windows"
    vmpal run "CI Windows" --isolated --copy-in .:src --cwd src -- powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File build.ps1
    
  • macOS permite como máximo dos máquinas virtuales de macOS a la vez en un Mac. Ese recuento incluye las que ejecutas tú y las de otras apps. Así que ejecuta como máximo dos trabajos de macOS a la vez: un tercero falla de inmediato. --admin necesita antes una aprobación en la máquina virtual maestra, y vmpal help exec explica cómo.

vmpal help ci tiene más información.