본문으로 이동

문서 명령줄 명령줄

CI/CD

vmpal run은 VM의 새 클론에서 CI 작업을 실행한 다음 클론을 삭제합니다. 작업마다 새 CI 러너처럼 깨끗한 머신을 받지만, 그 머신은 내 Mac에서 내 설정 그대로 동작합니다. VM은 빌드에 필요한 도구를 설치해 한 번만 준비하면 됩니다. GitHub Actions, GitLab CI 등 Mac에서 동작하는 모든 CI 러너와 함께 쓸 수 있습니다.

AI 에이전트에게 요청하기

코딩 에이전트가 이 설정을 대신해 줄 수 있습니다. VMPal은 이 안내를 vmpal help ci로 에이전트에게 제공합니다. 에이전트를 VMPal에 연결한 다음, 예를 들어 이렇게 요청하세요.

  • "내 Ubuntu VM의 새 클론에서 테스트를 실행하는 GitHub Actions 작업을 만들어 주세요."
  • "Visual Studio Build Tools를 설치해서 CI용 Windows VM을 준비해 주세요."
  • "내 CI VM에서 이 앱을 빌드하고 빌드 결과를 아티팩트로 보관하는 GitLab CI 작업을 추가해 주세요."

이 페이지의 나머지 부분은 동작 원리가 궁금할 때 참고하세요.

VM 한 번만 준비하기

골든 VM은 모든 작업이 시작되는 VM으로, 베이스 이미지와 같습니다. 빌드에 필요한 것을 골든 VM에 한 번만 설치하세요.

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는 download:windows, download:macOS처럼 설치할 수 있는 시스템을 보여 줍니다.
  • 새 VM은 다운로드 폴더를 공유합니다. macOS가 VMPal의 다운로드 폴더 사용을 허용할지 한 번 물어볼 수 있습니다. Mac을 떠나 작업을 맡기기 전에 미리 응답해 두세요.

골든 VM은 종료된 상태로 두세요. run은 VM이 종료되어 있어야 동작합니다. vmpal stop이나 VM의 Shut Down으로 종료하세요. 창을 닫는 것만으로는 부족합니다. 창을 닫으면 VM이 종료되지 않고 저장됩니다.

나중에 골든 VM을 바꾸려면 VM을 시작해 변경한 다음 다시 종료하세요.

모든 작업에서 같은 화면

VM의 디스플레이는 창을 따라가며, 창이 열린 화면의 크기와 배율을 따릅니다. 그래서 UI 테스트와 스크린샷이 작업마다 달라질 수 있습니다. 골든 VM에 고정 디스플레이를 지정하면 모든 클론이 같은 디스플레이를 받습니다.

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

1440 × 900포인트에 2x 배율이므로 2880 × 1800픽셀입니다. 디스플레이는 어떤 화면에서도, 창이 전혀 없어도 이 크기를 유지합니다. 창에는 창 크기에 맞춰 조정되어 표시됩니다. Retina 배율이 없는 디스플레이는 @1x를 사용하세요. Windows VM에서 1x와 2x는 각각 100%, 200% 배율입니다. --display window를 쓰면 다시 창을 따라갑니다.

작업 실행하기

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

이 명령은 체크아웃한 저장소 같은 현재 폴더를 VM의 src에 복사합니다. 그곳에서 make test를 실행한 다음, src/out을 Mac의 ./out으로 다시 복사합니다. run이 하는 일을 순서대로 보면 다음과 같습니다.

  1. VM을 복제합니다. 클론은 쓰기가 일어나기 전까지 VM의 디스크를 공유하므로 복제는 즉시 끝납니다.
  2. 클론을 시작하고, 클론이 명령을 실행할 수 있을 때까지 기다립니다.
  3. --copy-in으로 지정한 항목을 복사해 넣습니다.
  4. 명령을 실행하고 출력을 나오는 대로 보여 줍니다.
  5. 명령이 실패해도 --copy-out으로 지정한 항목을 복사해 옵니다.
  6. 클론을 끄고 완전히 삭제합니다.

클론의 이름과 ID는 표준 오류로 출력합니다.

다른 CI 단계처럼 종료 코드가 성공과 실패를 결정합니다. run은 명령의 종료 코드로 종료하므로, 작업의 성공 여부는 명령의 결과를 따릅니다. 다음 두 코드는 run 자체의 코드입니다.

종료 코드 의미
124 명령이 --timeout(기본값 2시간)을 넘겨 실행됨
125 run 자체가 맡은 일을 하지 못함. 예를 들어 클론이 10분 안에 준비되지 않은 경우

--isolated 옵션은 클론을 Mac과 분리합니다. 클론은 복사한 파일 외에는 Mac의 어떤 것도 받지 않습니다. 공유 폴더, 포워딩된 포트, 클립보드, 드래그 앤 드롭, 스피커, 마이크가 없으며 공유 네트워크만 사용합니다. --isolated 없이 실행하면 클론은 다운로드 폴더처럼 골든 VM이 공유하는 항목을 그대로 가집니다. 그러면 모든 작업이 그 폴더를 읽고 바꿀 수 있습니다. 아니면 vmpal set "CI Ubuntu" --unshare Downloads로 골든 VM에서 공유를 한 번만 해제해 두세요.

옵션 기능
--copy-in <Mac path>:<VM path> 명령을 실행하기 전에 cp처럼 지정한 항목을 클론에 복사합니다. 여러 번 지정할 수 있습니다
--copy-out <VM path>:<Mac path> 명령을 실행한 뒤 지정한 항목을 복사해 옵니다. 명령이 실패해도 복사합니다. 여러 번 지정할 수 있습니다
--cwd, --admin, --timeout exec에서와 같이 동작합니다. VM 경로는 사용자의 홈 폴더를 기준으로 합니다. --admin을 쓰면 복사도 관리자 권한으로 합니다
--env NAME=value 명령에 환경 변수를 설정합니다. --env NAME은 이 Mac의 NAME 값을 전달하므로 비밀 값이 명령줄에 드러나지 않습니다
--cpus <n>, --memory <GB> 클론의 CPU와 메모리를 설정합니다
--name <name> 클론의 이름을 지정합니다. 기본값은 <VM> run <8 hex digits>입니다
--isolated 복사한 파일 외에는 Mac의 어떤 것도 클론에 주지 않습니다
--in-background 창 없이 클론을 시작합니다
--no-sign-in 클론의 로그인 화면에서 로그인하지 않습니다
--keep 클론을 남겨 두어 살펴볼 수 있게 합니다. 나중에 vmpal delete로 삭제하세요

취소

작업이 취소되면 CI는 SIGINT나 SIGTERM을 보냅니다. 그러면 run이 명령을 중지하고 클론을 삭제합니다. 시그널을 한 번 더 받으면 run은 즉시 종료하고, 클론의 이름과 클론을 삭제하는 명령을 출력합니다.

남은 클론이 있으면 vmpal list에 표시됩니다. vmpal delete <VM> --force --permanently로 삭제하세요.

단계별로 실행하기

run은 명령을 하나만 실행합니다. 한 클론에서 여러 명령을 실행하려면 run의 단계를 직접 수행하세요. 이때 클론은 격리되지 않으므로 --isolated 없이 run을 쓴 것과 같습니다.

trap 줄은 단계가 어떻게 끝나든 클론을 삭제합니다. 성공, 실패, 취소, 셸의 -e로 인한 중단이 모두 해당합니다. GitHub의 셸은 -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

Mac에 자체 호스팅 러너를 설치하세요. 그러면 작업은 다음과 같습니다.

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은 vmpal을 해당 단계의 프로세스 자체로 만듭니다. 그래서 작업이 취소되면 시그널이 vmpal에 전달되고, vmpal이 클론을 삭제합니다.
  • if: always()는 테스트가 실패해도 out을 업로드합니다.

GitLab CI

Mac에 셸 실행기(shell executor)로 GitLab Runner를 설치하세요. 그러면 작업은 다음과 같습니다.

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는 테스트가 실패해도 out을 보관합니다.

알아 두기

  • 러너. 러너는 로그인한 사용자의 LaunchAgent로 Mac에 설치하세요. GitHub와 GitLab의 러너는 이 방식으로 설치됩니다. Mac이 잠자기 상태가 되지 않게 하세요. vmpal은 백그라운드에서 VMPal을 엽니다. 작업은 메모리와 CPU가 허용하는 만큼 각자의 클론에서 동시에 실행됩니다.

  • Windows는 로그인 화면에서 시작합니다. run은 VMPal이 해당 VM용으로 저장해 둔 비밀번호로 로그인합니다. 저장된 비밀번호가 없으면 누군가 로그인할 때까지 기다리다가 10분 후 중단합니다.

    • 비밀번호가 더 이상 맞지 않으면 골든 VM에서 업데이트하세요. 클론은 골든 VM에서 비밀번호를 복사합니다. 골든 VM의 Settings › General › Account › Update Password… 버튼을 클릭하거나 vmpal set "CI Windows" --account-password-file <file>을 실행하세요. 파일 자리에 -를 지정하면 표준 입력에서 비밀번호를 읽습니다.
    • 명령에는 cmd.exe나 powershell.exe가 필요합니다. --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는 Mac 한 대에서 동시에 macOS VM을 최대 두 개까지만 허용합니다. 직접 실행한 VM과 다른 앱의 VM도 포함됩니다. 따라서 macOS 작업은 한 번에 최대 두 개만 실행하세요. 세 번째 작업은 즉시 실패합니다. --admin을 쓰려면 먼저 골든 VM에서 승인해야 하며, 방법은 vmpal help exec에서 확인하세요.

자세한 내용은 vmpal help ci를 참고하세요.