맥미니 self-hosted 러너에 테스트와 배포를 맡겼다 초안

맥미니에서 테스트를 돌리면 17개가 실패했다. 가상환경이 Python 3.14였고 패키지 몇 개가 빠져 있었다. 맥북은 3.12였고 결과가 달랐다. 정작 운영은 둘 중 어느 가상환경도 아닌 Docker 이미지(Python 3.12에 전체 의존성) 안에서 돈다. 어느 쪽 결과를 믿어야 하는지가 분명하지 않았다.

커뮤니티용 텔레그램 봇을 맥미니에서 Docker 컨테이너로 운영하고, 코드는 맥북에서 고친다. 2026년 8월 하순까지 테스트는 각 기계에 그때그때 만든 가상환경에서 돌렸고, 배포는 맥미니에 ssh로 들어가 손으로 했다. push한 뒤 맥미니에서 pull하고 재시작 스크립트를 실행하는 순서를 매번 사람이 밟았고, 테스트를 건너뛰어도 막는 것이 없었다.

호스트 가상환경에서 통과한 테스트가 말해 주는 건 “그 가상환경에서 된다”까지다. 그래서 맥미니에 GitHub Actions self-hosted 러너를 하나 두고, 테스트를 운영 이미지 안에서 돌린 뒤 통과하면 배포하게 묶었다.

launchd로 띄운 러너는 docker를 찾지 못했다

러너는 맥미니에 설치해 launchd로 상주시켰다. 워크플로는 하나다. PR에서는 테스트만 돌고, main에 push되면 테스트를 통과한 뒤 배포한다. 수동 실행도 열어 두었다.

concurrency:
  # PR 은 같은 브랜치의 이전 실행을 취소, main 은 줄 세워 순서대로
  group: ci-${{ github.event_name == 'pull_request' && github.head_ref || 'main' }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  test:
    runs-on: [self-hosted, my-bot]
    steps:
      - run: echo /opt/homebrew/bin >> "$GITHUB_PATH"
      - uses: actions/checkout@v4
      - run: ./scripts/test_docker.sh
  deploy:
    if: github.event_name != 'pull_request'
    needs: test
    runs-on: [self-hosted, my-bot]

각 job의 첫 step이 GITHUB_PATH에 homebrew 경로를 넣는다. 러너가 docker를 찾지 못해서 넣은 줄이다. 내 터미널에서는 셸 설정 파일이 PATH를 채워 주지만 launchd가 띄운 프로세스는 그 파일을 읽지 않아서, 러너의 PATH에는 homebrew가 없었다.

concurrency는 이벤트 종류에 따라 다르게 동작한다. PR은 같은 브랜치에 새 커밋이 오면 이전 실행을 취소하고, main은 취소하지 않고 줄을 세운다. 배포가 도는 중에 취소되면 컨테이너가 교체 도중에 멈출 수 있다.

배포 job은 checkout 액션을 쓰지 않는다

actions/checkout은 러너의 작업 폴더에 저장소를 받는다. 운영 컨테이너가 보는 폴더는 따로 있다. 설정 파일과 데이터 볼륨이 마운트된 운영 checkout이고, 러너 작업 폴더에는 그 설정도 데이터도 없다.

deploy job은 working-directory를 운영 checkout으로 잡고, 그 폴더를 main으로 fast-forward한 뒤 재시작 스크립트를 부르는 일만 한다.

if [[ -n "$(git status --porcelain --untracked-files=no)" ]]; then
  echo "::error::운영 checkout 에 커밋 안 된 변경이 있어 배포를 멈춥니다"
  exit 1
fi
git fetch --quiet origin main
git checkout --quiet main
git pull --ff-only --quiet origin main

앞의 검사는 운영 checkout에 커밋되지 않은 변경이 있으면 배포를 멈춘다. 누군가 운영 폴더에서 직접 파일을 고쳐 둔 상태로 pull하면 충돌하거나, 더 나쁘게는 고친 내용이 섞인 채 배포된다. 맥미니에서 개발할 일이 있으면 별도 clone에서 한다는 규칙도 같이 정했다. --ff-only도 같은 이유로 넣었다. 운영 checkout에서 merge 커밋이 만들어지는 일은 없어야 한다.

배포가 실패하면 봇 소유자에게 DM으로 실패한 커밋의 제목과 실행 링크를 보낸다.

테스트는 운영 Dockerfile로 빌드한 이미지 안에서 돈다

테스트 스크립트는 운영이 쓰는 바로 그 Dockerfile로 이미지를 빌드하고, 그 이미지로 컨테이너를 띄워 테스트를 돌린다.

이미지에는 테스트 폴더가 들어 있지 않다. Dockerfile이 애플리케이션 코드만 복사한다. 그래서 checkout 전체를 /src에 바인드 마운트하고 PYTHONPATH=/src로 잡았다. import되는 것은 마운트된 소스이고, 이미지에서 빌리는 것은 파이썬 버전과 의존성뿐이다. PR의 코드를 운영과 같은 런타임에서 돌리는 셈이라, CI를 통과했다는 건 운영 이미지에서 그 코드가 import된다는 뜻이 된다.

매번 이미지를 빌드하지만 느리지 않았다. 테스트용 빌드와 배포용 compose 빌드가 Docker 빌드 캐시를 공유한다. 맥미니에서 이미지 빌드는 3초, 테스트 전체는 18초였다. CI가 먼저 빌드해 두면 뒤따르는 배포 스크립트의 빌드도 거의 바로 끝난다.

방어 코드도 하나 넣었다. 컨테이너 안에서 테스트 파일이 하나도 안 보이면 “통과 0, 실패 0”으로 끝내지 않고 오류로 끝낸다. 맥에서 Docker를 돌리는 colima는 호스트의 일부 경로만 VM과 공유해서, 공유 범위 밖에서 실행하면 컨테이너 안에서 소스가 보이지 않는다. 테스트가 0개 돈 것이 초록으로 찍히면 안 된다.

첫 커밋 2분 뒤에 고친 빈 배열

테스트 스크립트는 조건에 따라 추가 마운트 옵션을 배열에 담아 docker run에 넘긴다. 추가할 것이 없으면 배열이 빈다. 이게 맥미니에서는 통과했는데 맥북에서는 죽었다. 첫 커밋을 올리고 2분 뒤에 고쳤다.

맥에 기본으로 들어 있는 bash는 3.2이고, 이 버전은 set -u 아래에서 빈 배열을 "${arr[@]}"로 펼치면 unbound variable 오류를 낸다. 맥북의 #!/usr/bin/env bash는 이 3.2를 집었고, 맥미니에서는 homebrew의 bash 5가 잡혔다. env는 PATH에서 먼저 나오는 것을 고른다. 위에서 GITHUB_PATH에 넣은 homebrew 경로가 docker뿐 아니라 스크립트를 실행하는 셸 버전에도 영향을 주고 있었다.

# bash 3.2 + set -u: 빈 배열 "${arr[@]}" 는 unbound variable 로 죽는다
docker run --rm -v "$PWD:/src" ${extra_mounts[@]+"${extra_mounts[@]}"} -w /src ...

${arr[@]+"${arr[@]}"}는 배열에 원소가 있을 때만 펼치는 관용구이고 두 버전 모두에서 동작한다.

10월에 붙인 배포 뒤 정리

10월에는 deploy job 끝에 정리 스크립트를 붙였다. 맥미니의 개발용 폴더가 계속 뒤처진 것이 계기였다. 고친 사본이 미커밋 상태로 남아 main을 당기지 못했고, 어느 날은 186 커밋, 다음 날은 25 커밋 뒤처져 있었다. 예전 브랜치 흐름에서 생긴 원격 브랜치 여덟 개도 5~7주째 남아 있었다.

스크립트는 이미 main에 들어간 원격 브랜치, worktree, 사본만 지운다. 아직 배포되지 않은 진짜 변경과 최근 30분 안에 고친 파일은 남기고, 되돌리기 전에 백업을 만든다. 이 step은 continue-on-error로 두어서 정리가 실패해도 배포 결과는 초록으로 남는다.

알려진 실패 목록은 두 달 뒤에 지웠다

게이트를 처음 걸던 날, main에는 이미 깨져 있는 테스트가 네 개 있었다. 전부 고친 뒤에 게이트를 걸면 게이트가 늦어진다. 그래서 파일 이름을 목록 파일에 적어 두고, 목록에 있는 테스트는 실행은 하되 실패해도 배포를 막지 않게 했다. 출력에는 통과, 실패와 별도로 “알려진 실패”로 찍힌다. 고치면 목록에서 지우고, 지우는 순간부터 다시 게이트에 걸리게 할 계획이었다.

두 달 뒤인 10월 하순에 이 목록을 정리했다. 그때 남아 있던 것은 세 개였다(나머지 하나가 언제 어떻게 목록에서 빠졌는지는 이번에 읽은 커밋 범위에서는 확인하지 못했다). 들여다보니 셋 다 코드는 멀쩡했고 테스트가 낡아 있었다. 하나는 이미 없어진 함수를 패치하고 있었고, 하나는 테스트용 가짜 객체에 그 사이 새로 생긴 메서드가 없었고, 하나는 내부용 라벨을 화면에 보이는 문구로 착각한 단언이었다. 고치지 않고 지웠다. 커밋 메시지에 적은 이유는 “두 달 동안 아무것도 지키지 못해 지운다”였다.

목록 덕에 게이트는 빨리 걸었다. 기한은 정하지 않았다. 그 세 테스트는 두 달 동안 매번 실행되고 매번 실패하면서 아무 정보도 주지 않았다.