곧 제공

GitLab CI

GitLab Runner custom executor가 잡마다 Mac VM을 만들고, SSH로 실행한 뒤 지웁니다.

아직 호출할 수 없습니다. 아래 계약은 공개 Go SDK와 통합 패키지가 이미 쓰는 계약이라 확정되어 있지만, 서버 구현은 만드는 중입니다. 호출할 수 있게 되면 변경 기록에 공지합니다.

integrations/gitlab-executor는 GitLab Runner의 custom executor입니다. 잡마다 gitlab-<CI_JOB_ID> 이름의 인스턴스를 만들고 status=running이 될 때까지 폴링한 뒤 SSH로 스크립트를 실행하고, cleanup에서 삭제합니다. 고정된 30초 대기는 쓰지 않습니다.

필요한 것

bash, curl, jq, ssh
계정 API 키(Bearer)와 프로젝트 id
계정에 등록한 SSH 개인키

[[runners]]
  name = "cicd-mac"
  executor = "custom"
  environment = [
    "CICD_PROJECT_ID=00000000-0000-0000-0000-000000000000",
    "CICD_IMAGE=macos-tahoe",
    "CICD_TYPE=mac-m4-c8-m12",
    "CICD_REGION=kr-seoul-1",
    "CICD_SSH_KEY_PATH=/home/runner/.ssh/id_ed25519"
  ]

  [runners.custom]
    config_exec  = "/opt/cicd/gitlab-executor/config.sh"
    # The API key comes from a 0600 file. There is no --api-key flag.
    # The API key comes from a 0600 file. Endpoints are NOT flags: config.sh logs
    # a warning and ignores --api-base-url / --ssh-gateway. Put them in the trusted file.
    config_args  = [
      "--api-key-file", "/etc/cicd/api-key"
    ]
    prepare_exec = "/opt/cicd/gitlab-executor/prepare.sh"
    run_exec     = "/opt/cicd/gitlab-executor/run.sh"
    cleanup_exec = "/opt/cicd/gitlab-executor/cleanup.sh"

신뢰 경계

API 주소와 SSH 게이트웨이는 설치 시점에 경로가 고정된 신뢰 설정 파일 /etc/cicd/runner.env에서만 옵니다(러너 프로세스 환경도 같은 값을 줄 수 있습니다). config.sh의 --api-base-url·--ssh-gateway 플래그는 경고를 남기고 무시합니다 — 저장하지 않습니다. .gitlab-ci.yml의 CUSTOM_ENV_CICD_API_BASE_URL·CUSTOM_ENV_CICD_SSH_GATEWAY·CUSTOM_ENV_CICD_SSH_TARGET도 무시하고 경고만 남깁니다. 주소는 https://에 호스트가 cicd.im이거나 그 하위 도메인이어야 하며, 신뢰 파일이 CICD_ALLOW_CUSTOM_BASE_URL=1을 설정한 경우에만 예외입니다. 잡별 이미지·타입·리전·프로젝트 id는 잡 변수로 받아도 됩니다.

주요 환경 변수

변수	기본값	용도
`CICD_API_KEY`	없음(필수)	계정 API 키. `CICD_API_KEY_FILE`도 됩니다. 명령줄 플래그로는 받지 않습니다.
`CICD_API_BASE_URL`	`https://cicd.im/api/v1/`	API 루트. 러너 설정에서만.
`CICD_SSH_GATEWAY`	기본값 없음	SSH 게이트웨이 호스트. 러너 설정에서만. 게이트웨이가 공지되면 설정하세요 — 비어 있으면 잡이 SSH 단계에서 그 사실을 말하며 실패합니다.
`CICD_PREPARE_TIMEOUT_SECONDS`	`300`	`running`까지 기다리는 총 시간
`CICD_MAX_RETRY_AFTER`	`60`	`Retry-After`·백오프 상한(초)
`CICD_PROXY_TUNNEL_ENABLED`	`false`	러너 호스트 프록시로 역터널

수명 주기

config — driver JSON을 출력하고 잡 전용 상태 디렉터리를 만듭니다. 주소·게이트웨이는 저장하지 않고 신뢰 파일에서 읽습니다. API 키는 절대 출력하지 않습니다.
prepare — POST /instances 후 running까지 폴링합니다. 종료 상태는 즉시 실패로 처리하고 status_reason을 출력합니다. 429·5xx는 Retry-After를 존중하며 제한된 백오프로 재시도하고, POST 응답을 잃었을 때는 같은 이름을 조회해 VM을 두 번 만들지 않습니다.
run — ssh -i <key> -- <id>@<gateway> bash -s로 잡 스크립트를 표준 입력에 흘려 보냅니다.
cleanup — gitlab-<CI_JOB_ID> 이름의 인스턴스를 모두 삭제합니다. 목록 조회가 2xx가 아니면 "지울 게 없음"이 아니라 시스템 실패로 처리하고, 삭제의 404는 성공한 no-op입니다.

잡 스크립트 실패는 BUILD_FAILURE_EXIT_CODE, API·SSH·prepare 실패는 SYSTEM_FAILURE_EXIT_CODE로 구분합니다. API 키는 0600 헤더 파일로 curl에 전달되어 표준 출력·표준 오류·set -x 추적에 남지 않습니다.

패키지의 자동 테스트는 localhost 목 API와 가짜 ssh만 씁니다. 테스트 통과는 실제 인스턴스나 SSH 게이트웨이가 동작한다는 증거가 아닙니다.