지금 확인할 것: 실행 계정, 실제 셸, Homebrew 설치 접두 경로를 먼저 확인한 뒤 해당 환경에서 brew shellenv가 불리는지 점검하세요. 이번 주에는 다음 CI 실행 전에 같은 계정과 셸로 재검증하세요. 대화형 터미널에서만 동작한다면 설치를 반복하거나 권한을 넓히지 말고, 실패하는 자동 실행 환경을 고치면 됩니다.
이 글은 SSH로 원격 Mac에서 Homebrew를 쓰다가 명령이 실패한 개발자를 위한 안내입니다.
macOS CI와 백그라운드 작업을 관리하며 실행 환경을 추적해야 하는 엔지니어에게도 해당합니다.
공유 원격 Mac의 계정과 셸 구성을 관리하는 플랫폼 담당자도 확인할 수 있습니다.
원격 맥 홈브루 명령 오류의 범위 분리
먼저 실패한 것이 brew 자체인지, Homebrew로 설치한 도구인지, 특정 자동 작업에서만 발생하는지 구분하세요. 오류 문구만 보고 재설치하면 실제 원인인 PATH 누락이나 실행 계정 차이를 놓칠 수 있습니다.
가령 SSH 터미널에서 brew --version은 되지만 CI에서 git을 찾지 못한다면, 우선 확인할 대상은 Homebrew 설치 상태가 아니라 CI의 실행 환경입니다. 반대로 brew 자체가 셸에서 발견되지 않는다면 실행 파일 경로와 셸 초기화를 살펴야 합니다.
SSH 접속 뒤에만 brew를 찾지 못하는 경우는 무엇을 확인해야 하나요? 먼저 로그인 계정과 명령을 실행한 셸을 확인하세요. SSH로 접속해 입력한 명령과 원격 명령 실행은 셸 초기화 방식이 다를 수 있으므로, 같은 조건이라고 가정하지 말고 실패한 명령을 같은 접속 방식으로 다시 실행해야 합니다.
02실제 설치 접두 경로와 셸 확인
Homebrew 공식 문서가 안내하는 기본 접두 경로는 Apple Silicon에서 /opt/homebrew, Intel Mac에서 /usr/local입니다. 이는 문서에 기재된 기본값이지, 현재 원격 호스트에서 확인한 경로가 아닙니다. 실제 위치는 해당 Mac에서 직접 확인하세요. 공식 설치 안내의 접두 경로와 기본 설치 경로 설명을 기준으로 삼되, 다른 경로에 설치했을 가능성도 열어 두어야 합니다.
id -un
printf 'SHELL=%s\n' "$SHELL"
ps -p $$ -o comm=
uname -m
command -v brew
brew --prefix
command -v brew가 아무 경로도 돌려주지 않으면 현재 셸의 PATH에 실행 파일이 없는 상태일 수 있습니다. brew --prefix는 brew가 실행될 때 확인하는 명령이므로, brew를 아예 찾지 못한다면 이 명령만으로 설치 위치를 알아낼 수는 없습니다. 실제 파일 위치를 확인한 뒤 그 경로를 바탕으로 다음 조치를 정하세요. Homebrew 명령 문서는 brew --prefix와 shellenv를 포함한 사용법을 설명합니다.
Apple Silicon인지 Intel인지 확인하더라도 그 결과만으로 실제 Homebrew 경로를 단정하지 마세요. 셸이 다른 아키텍처 방식으로 실행되거나 설치가 기본 위치를 벗어났을 수 있습니다. uname -m 결과, 실제 실행 파일, brew --prefix 결과를 함께 맞춰 보세요.
| 확인 대상 | 기본 경로 또는 확인 수단 | 판단 기준 |
|---|---|---|
| Apple Silicon의 기본 접두 경로 | /opt/homebrew (공식 설치 안내) |
현재 호스트의 실제 실행 파일과 일치하는지 확인합니다. |
| Intel Mac의 기본 접두 경로 | /usr/local (Homebrew FAQ) |
기본 경로라고 가정하지 말고 현재 계정에서 확인합니다. |
| 실행 중인 셸 | ps -p $$ -o comm= |
$SHELL에 적힌 로그인 기본 셸과 현재 셸이 같은지 비교합니다. |
SSH 셸 초기화와 PATH 누락
터미널에서 동작하고 SSH 명령에서 실패한다면 셸 초기화 파일을 살펴보세요. 셸은 로그인 여부와 대화형 여부에 따라 읽는 파일이 달라질 수 있습니다. 따라서 brew shellenv 설정이 한 파일에 있다는 사실만으로 모든 실행 경로에 적용된다고 볼 수 없습니다.
zsh는 실행 조건에 따라 시작 파일을 다르게 읽습니다. zsh 공식 시작 파일 설명에서 현재 조건에 해당하는 파일을 확인하세요. bash 등 다른 셸의 설정을 zsh 규칙과 섞지 말고, 우선 ps -p $$ -o comm=으로 실제 셸을 식별합니다.
현재 셸에서 다음 결과를 비교해 보세요.
printf '%s\n' "$PATH"
command -v brew
실제 설치 접두 경로를 확인한 뒤, 해당 설치의 brew shellenv 출력이 현재 실행 경로의 PATH에 반영되는지 확인합니다. 설치 문서의 예시 경로를 그대로 붙여 넣지 마세요. 초기화 파일을 수정할 때는 해당 셸이 실제로 읽는 파일만 바꾸고, 같은 줄을 여러 파일에 중복 추가하지 마세요. 설정 변경 뒤에는 새 SSH 접속을 열어 동일한 명령을 재실행해야 합니다.
CI와 백그라운드 작업의 계정 추적
CI Runner, 예약 작업, 서비스는 관리자의 대화형 터미널과 다른 사용자나 셸로 실행될 수 있습니다. brew가 관리자 계정에서 보인다는 사실은 작업 실행 계정에도 같은 PATH가 있다는 증거가 아닙니다.
Homebrew가 설치되어 있는데 CI에서만 도구를 실행할 수 없다면 어떻게 해야 하나요? 작업 로그에 id -un, 현재 셸, PATH, command -v brew 결과를 출력해 실제 실행 맥락을 확인하세요. 그 계정의 셸이 읽는 환경 설정을 고친 뒤 같은 CI 작업으로 재검증해야 합니다. GitHub Actions 자체 호스팅 Runner의 모니터링 안내도 서비스 상태뿐 아니라 Runner가 실제 작업을 수행하는지 확인하도록 설명합니다.
작업 설정을 조사할 때는 셸 종류와 실행 계정뿐 아니라, 서비스가 어떤 환경 변수를 넘기는지도 기록하세요. 예약 작업 설정에 한 줄을 추가하는 것으로 해결될 수 있지만, 셸 시작 파일이 작업에서 읽히지 않는다면 그 수정은 효과가 없습니다. 로그에 진단 결과가 남지 않으면 수정 전후를 비교하기 어렵습니다.
05접두 경로와 권한 문제의 안전한 진단
brew 파일이 존재하지만 실행할 수 없거나 읽기 권한 오류가 발생한다면, 먼저 접두 경로와 상위 디렉터리의 소유자 및 권한을 확인하세요. 현재 계정이 예상한 계정인지도 다시 확인해야 합니다. 공유 Mac에서는 다른 사용자가 설치한 파일을 현재 계정이 실행하려는 상황일 수 있습니다.
Homebrew의 관리자 안내는 설치와 관리에 사용하는 계정 및 권한 경계를 설명합니다. Mac 관리자를 위한 Homebrew 안내를 확인하고, 소유자와 디렉터리 권한이 해당 원칙에 맞는지 살펴보세요. 전체 경로에 재귀적으로 소유권을 바꾸거나, 모든 작업을 관리자 권한으로 실행하거나, 원인 확인 전에 다시 설치하는 것은 기본 해결책이 아닙니다. 그런 변경은 원래 문제를 가리고 다른 계정의 실행까지 깨뜨릴 수 있습니다.
| 관찰된 증상 | 우선 확인할 항목 | 피해야 할 조치 |
|---|---|---|
brew를 찾지 못함 |
실제 셸, PATH, 실행 파일 위치 |
확인 전 반복 설치 |
| 설치 도구만 찾지 못함 | 해당 도구의 설치 접두 경로와 PATH |
brew 자체 오류로 단정 |
| 권한 오류가 발생함 | 실행 계정, 접두 경로 소유자와 디렉터리 권한 | 경로 전체의 무차별 권한 변경 |
재검증 결과에 따른 수정과 노드 판단
수정은 오류가 발생한 실행 맥락에 한정하세요. 아래 항목을 순서대로 확인하면 셸 설정 문제인지, 계정 차이인지, 노드 자체의 문제인지 나눌 수 있습니다.
- [ ] 실패한 명령과 전체 오류 문구, 실행 계정을 기록합니다.
- [ ] 현재 셸과
PATH,command -v brew결과를 확인합니다. - [ ] 실제 실행 파일 위치와
brew --prefix결과를 대조합니다. - [ ] 로그인 셸, SSH 원격 명령, 실제 CI나 백그라운드 작업에서 각각 대표 명령을 실행합니다.
- [ ] 작업 로그에서 실행 계정, 셸, 경로, 종료 상태와 명령 결과를 확인합니다.
- [ ] 문제가 한 작업에만 남으면 해당 작업 환경을 수정하고, 설치 상태나 노드 기준선이 불확실하면 노드 재구성을 검토합니다.
자동 작업이 어떤 셸과 계정을 쓰는지 어떻게 확인하나요? 실행 파일 이름이나 Runner 설정만으로 추측하지 마세요. 작업 자체에서 id -un, ps -p $$ -o comm=, printf '%s\n' "$PATH"를 출력하고, 로그에 남은 결과로 실제 실행 계정과 셸을 확인해야 합니다.
| 검증 위치 | 실행할 확인 | 수정이 필요한 경우 |
|---|---|---|
| 대화형 셸 | command -v brew, brew --prefix |
현재 셸의 초기화 또는 경로 설정이 누락된 경우 |
| SSH 원격 명령 | 계정, 셸, PATH, 대표 명령 |
SSH 실행 경로에서 필요한 초기화가 적용되지 않는 경우 |
| CI 또는 백그라운드 작업 | 작업 로그의 계정, 셸, 경로와 명령 결과 | 해당 작업의 서비스 환경이나 실행 계정이 다른 경우 |
대화형 셸만 실패하고 SSH와 CI는 정상이라면 그 셸 설정을 고치면 됩니다. CI에서만 실패한다면 Runner의 실제 계정과 서비스 환경을 대상으로 수정하세요. 여러 실행 경로에서 설치 위치나 파일 접근이 서로 다르거나 노드 기준선을 신뢰할 수 없다면, 권한을 더 넓히기보다 실행 노드를 정비하거나 재구성하는 편이 안전합니다.
현재 쓰는 환경이 Linux 서버뿐이면 macOS 전용 도구 체인을 실행할 수 없습니다. 로컬 Mac에 맡기면 잠자기나 접속 중단 때 자동 작업이 멈출 수 있고, 공유 Mac은 계정별 셸 설정이 달라져 재현성이 흔들릴 수 있습니다. 이 조건을 해결하려고 불필요하게 설치와 권한을 반복 변경하기보다, 원격 Mac 개발 환경의 선택지를 먼저 비교하세요. 안정적으로 재현할 macOS 환경이 없고 일정 기간만 테스트할 필요가 있다면 VpsMesh의 Mac mini 원격 사용 옵션을 검토할 수 있습니다. 다만 장기간 지속되는 고정 부하나 물리 인터페이스가 필요한 작업이라면 임대보다 전용 실기기가 더 적합할 수 있습니다.