DevOps / CI/CD

macOS 27 Docker CI용 자체 호스팅 Mac은 어떻게 배포하나요? 2026 가이드

macOS 27 Docker CI용 자체 호스팅 Mac은 어떻게 배포하나요? 2026 가이드

Last updated: 2026년 10월 4일. GitHub 자체 호스팅 runner 문서와 Docker 설치·라이선스·Buildx 문서를 기준으로 확인했습니다.

GitHub 공식 문서에 따르면 Docker 컨테이너 액션이나 서비스 컨테이너를 실행하는 자체 호스팅 runner에는 Linux가 필요합니다. 따라서 macOS 27 자체 호스팅 Mac은 검증된 호스트 측 Docker 빌드에 쓰고, 해당 컨테이너 작업은 Linux runner로 분리해야 합니다. Docker Desktop의 macOS 지원 범위와 라이선스, 실제 대여 환경의 권한은 배포 시점에 각각 확인해야 합니다. GitHub 자체 호스팅 runner 요구 사항

이 안내는 GitHub Actions에 Docker 이미지 빌드를 넣으려는 DevOps 엔지니어를 위한 내용입니다.
macOS 작업과 이미지 빌드를 한 파이프라인에 넣으려는 개발팀은 Mac과 Linux 사이의 작업 경계를 정할 수 있습니다.
Mac CI 환경을 검토하는 책임자는 설치 조건과 라이선스, 유지 관리 부담을 먼저 확인할 수 있습니다.

작업 종류부터 나누면 Mac과 Linux의 경계가 보입니다

Docker 명령을 실행한다는 사실만으로 모든 Docker 작업이 Mac runner에서 가능해지는 것은 아닙니다. 먼저 워크플로를 다음처럼 분류합니다.

  • Mac이 맡을 수 있는 후보: runner 호스트에서 실행되는 셸 단계, Docker CLI로 시작하는 이미지 빌드. 단, Docker Desktop 설치와 daemon 연결이 목표 환경에서 확인되어야 합니다.
  • Linux로 보내야 하는 작업: GitHub Actions의 Docker 컨테이너 액션과 서비스 컨테이너. GitHub 문서가 자체 호스팅 환경에서 Linux를 요구합니다.
  • 별도 검증이 필요한 작업: 특정 CPU 아키텍처용 이미지 빌드, 외부 레지스트리 푸시, 가상화 기능이나 관리자 권한에 의존하는 단계.
작업 유형 Mac 자체 호스팅 runner Linux runner
호스트 셸에서 실행하는 빌드 스크립트 Docker Desktop과 daemon을 확인한 뒤 시험 Linux 기반 작업에 적합
Docker 컨테이너 액션 대체 대상으로 간주하지 않음 GitHub 문서의 요구 조건에 맞음
서비스 컨테이너 대체 대상으로 간주하지 않음 GitHub 문서의 요구 조건에 맞음
macOS 전용 후속 단계 해당 단계를 맡길 수 있음 macOS 실행 환경이 아니므로 분리

Mac runner가 컨테이너 액션까지 처리하게 구성하면 안 되나요?
Docker CLI가 설치되어 있어도 runner의 운영체제 요구 조건은 바뀌지 않습니다. 컨테이너 액션이나 서비스 컨테이너가 필요한 job은 Linux runner로 보내고, Mac에서는 호스트 셸 기반 빌드처럼 실제 확인을 마친 작업만 실행합니다.

주의: Docker Desktop의 macOS 27 지원 여부는 고정된 전제로 두지 마세요. Docker의 Mac 설치 안내에서 배포 시점의 지원 범위를 확인하고, 목표 Mac에서 설치와 첫 실행까지 검증해야 합니다.

설치 전에 지원 범위와 사용 권한을 대조합니다

macOS 27이 설치되어 있다는 것만으로 Docker Desktop이 지원되거나 실행된다고 판단할 수는 없습니다. Apple의 macOS 27 공개 자료와 Docker의 현재 설치 요구 조건을 함께 확인합니다. Docker 문서에서 지원하는 macOS 버전인지, 대상 Mac의 프로세서 구조가 필요한 작업과 맞는지 살펴봅니다.

라이선스도 따로 확인해야 합니다. Docker Desktop의 무료 사용 조건은 조직과 사용 목적에 따라 달라질 수 있으므로, 팀의 상황을 Docker Desktop 라이선스 안내와 대조합니다. 비용을 정할 때는 구독 여부뿐 아니라 이미지 저장 공간, 캐시 관리, 유지 보수 시간을 함께 고려합니다.

클라우드나 대여 Mac이라면 다음 조건을 공급 환경에서 확인합니다.

  • 가상화와 Docker Desktop 실행이 허용되는지
  • 설치 및 최초 실행에 필요한 권한이 제공되는지
  • runner가 GitHub와 필요한 이미지 저장소에 통신할 수 있는지
  • 재시작이나 접속 종료 뒤에도 runner와 Docker daemon을 운영할 방법이 있는지

Docker는 Mac 설치 과정에서 필요한 권한을 별도로 안내합니다. Docker의 Mac 권한 요구 사항을 참고하되, 문서상 조건이 대여 환경에서 자동으로 충족된다고 가정하지 마세요. 환경에 따라 가상화나 관리자 권한이 제한될 수 있습니다.

Mac을 빌려 Docker CI를 구성하기 전에 무엇을 확인해야 하나요?
지원되는 macOS인지, 팀이 Docker Desktop을 사용할 수 있는지, 공급 환경에서 설치와 가상화가 가능한지 확인합니다. 어느 한 항목이라도 확인되지 않으면 구매나 본격 배포를 미루고, 실제 목표 환경에서 먼저 시험합니다. 환경 비용을 검토하는 단계에서는 ProxyMac 요금 안내도 후보 비교 자료로 참고할 수 있습니다.

등록과 라우팅은 runner 라벨로 분리합니다

저장소 단위로 runner를 둘지 조직에서 관리할지는 접근 범위와 운영 책임에 따라 결정합니다. 등록 절차는 GitHub의 자체 호스팅 runner 추가 안내에 따릅니다. 등록 과정에서 실제로 부여되는 권한이나 화면 구성이 팀마다 같다고 단정하지 말고, 저장소 또는 조직 설정에서 확인합니다.

runner에는 운영체제와 아키텍처, 사용 목적을 구분하는 라벨을 설정합니다. 예를 들어 Mac 전용 job에는 self-hosted, macOS와 팀이 정한 용도 라벨을 지정할 수 있습니다. GitHub의 워크플로 runner 라우팅 안내에 따르면 job은 지정한 라벨 조건에 맞는 runner로 전달됩니다. 따라서 라벨은 편의상 붙이는 메모가 아니라 잘못된 runner에서 작업이 시작되는 것을 막는 배포 조건입니다.

라우팅 기준은 아래처럼 정합니다.

  • macOS 단계가 필요한 job이면 macOS와 용도 라벨을 지정합니다.
  • 컨테이너 액션이나 서비스 컨테이너가 필요한 job이면 Linux 라벨을 지정합니다.
  • 라벨만으로 가상화 지원이나 Docker 권한이 보장된다고 보지 않습니다. 해당 조건은 환경에서도 따로 검증합니다.

최초 이미지는 작게 빌드하고 결과물을 확인합니다

Mac에 GitHub Actions self-hosted runner를 등록한 뒤에는 운영용 파이프라인을 곧바로 연결하지 말고, 비생산용 저장소나 시험 job에서 확인합니다. 순서는 다음과 같습니다.

  1. Docker Desktop을 설치하고 직접 실행해 daemon이 준비되는지 확인합니다. 설치만 끝나고 첫 실행이나 권한 동의가 남아 있으면 다음 단계로 넘어가지 않습니다.
  2. runner 호스트 셸에서 docker version을 실행해 CLI와 daemon이 모두 응답하는지 확인합니다. CLI 정보만 출력되고 daemon 연결에 실패하면 이미지 빌드를 진행하지 않습니다.
  3. 의존성을 최소화한 Dockerfile로 docker buildx build --tag ci-smoke:test --load .을 실행합니다. Buildx 명령의 출력 방식과 캐시 설정은 공식 Buildx 빌드 문서에 맞춰 선택합니다.
  4. 빌드한 이미지가 로컬에 생성됐는지 확인하고, 실제 파이프라인에서 필요한 레지스트리 인증 정보로 시험 푸시를 수행합니다. 토큰은 로그나 저장소에 직접 남기지 말고 접근 권한을 제한합니다.
  5. 실패했을 때 로그, 이미지, 캐시를 정리하고 재실행합니다. 실패 원인이 권한인지, daemon 연결인지, 네트워크인지 구분할 수 있어야 운영 job에 연결할 수 있습니다.

여러 CPU 구조용 결과물이 필요하다면 빌드 플랫폼을 별도로 확인합니다. Buildx의 다중 플랫폼 안내에는 linux/amd64와 linux/arm64가 대상 예시로 제시됩니다. Docker 다중 플랫폼 빌드 문서를 기준으로 필요한 플랫폼과 결과물 형식을 설정하고, Mac에서 해당 빌드가 성공한다고 미리 약속하지 말고 목표 환경에서 실행합니다.

경험상 첫 검증에서 중요한 것은 빌드 시간보다 실패 원인을 분리할 수 있는 로그와 재현 절차입니다. 실제 속도나 아키텍처별 결과는 작업 부하와 환경에 따라 달라지므로, 시험 결과를 기록해 판단해야 합니다.

조건에 따라 Mac job과 Linux job을 선택합니다

  • macOS 전용 작업이 있고, Docker Desktop 지원·라이선스·daemon 연결까지 확인됐다면 해당 호스트 빌드 단계를 Mac runner에 둡니다.
  • Docker 컨테이너 액션이나 서비스 컨테이너를 사용하는 job이라면 Linux runner로 보냅니다.
  • Mac 환경의 가상화나 권한이 확인되지 않았다면 Docker 빌드를 전제로 배포하지 말고, 해당 job을 지원되는 Linux 환경에서 실행하거나 공급 조건을 먼저 해결합니다.
  • 두 운영체제가 모두 필요한 파이프라인이라면 job을 나누고, 이미지나 빌드 산출물을 전달하는 경로를 별도로 검증합니다.

이렇게 나누면 Mac에서 실행되는 job이 늘어나는 것을 성과로 착각하지 않게 됩니다. GitHub runner 문서의 운영체제 요구 조건과 실제 job 의존성을 함께 반영해야 합니다.

운영 단계에서는 자격 증명과 캐시를 관리합니다

자체 호스팅 runner는 등록 뒤에도 팀이 온라인 상태, 접근 권한, 토큰 보호, Docker 이미지와 캐시 정리, runner 소프트웨어 업데이트를 관리해야 합니다. 공용으로 접근 가능한 시스템에 민감한 저장소의 작업을 무심코 배정하지 않도록 runner 그룹과 워크플로 라우팅을 검토합니다.

정식 배포 전에는 실패 후 정리, 재시도, runner 재시작을 비생산 작업으로 확인합니다. macOS, Docker Desktop, 워크플로 파일의 변경 사항도 함께 기록합니다. 문제가 생겼을 때 마지막으로 바뀐 요소를 좁히기 쉽고, Docker Desktop이나 GitHub Actions가 요구 조건을 변경했을 때 재검증할 범위도 분명해집니다. 권한과 운영 문의를 정리할 때는 ProxyMac 도움말을 참고할 수 있습니다.

현재 Linux CI만 사용하는 팀은 macOS 전용 단계를 별도로 조율해야 하고, Mac을 직접 운영하면 설치 권한과 업데이트, runner 보안 및 캐시 정리까지 맡아야 합니다. 그렇다고 모든 팀에 대여 Mac이 맞는 것은 아닙니다. 지속적인 고정 부하를 장기간 운영하거나 물리 포트 접근이 필수라면 직접 보유한 장비가 더 적합할 수 있습니다. 임시 CI 검증이나 macOS와 Docker 빌드를 함께 시험할 환경이 필요하다면 ProxyMac 대여 Mac을 후보로 두되, 실제 작업에서 Docker Desktop 설치와 권한, Linux로 넘길 job을 먼저 검증한 뒤 도입 여부를 결정하는 편이 안전합니다.

맥 전용 빌드 환경을 원격으로 시작해 보세요

전용 물리 맥에서 맥 운영체제용 빌드와 지속적 통합 작업을 실행해 보세요.
터미널이나 원격 데스크톱으로 접속해 필요한 개발 도구와 작업 흐름을 직접 구성할 수 있습니다.