Jenkins에서 docker: command not found 트러블슈팅

문제 상황

Mac에 Homebrew로 Jenkins를 설치해 로컬에서 파이프라인을 실행하던 중, Docker 이미지를 빌드하는 단계에서 다음과 같은 오류가 발생했습니다.

터미널에서는 which docker 명령어를 통해 /usr/local/bin/docker 경로가 정상적으로 확인되지만, Jenkins 파이프라인 내에서는 해당 경로를 인식하지 못하는 문제가 발생했습니다.

원인

Jenkins는 macOS에서 launchd 서비스로 실행되는데, 이 환경에서는 사용자의 쉘 설정 파일(~/.zshrc, ~/.bash_profile 등)을 로드하지 않습니다.

그 결과, Jenkins 내부에서 사용하는 PATH에 /usr/local/bin 경로가 포함되지 않아 Docker 명령어를 찾을 수 없는 상황이 발생합니다.

📄 관련 공식 문서: Jenkins - Path setup for macOS users

해결 방법

1) Jenkins 설정 파일 열기

nano /opt/homebrew/opt/jenkins-lts/homebrew.mxcl.jenkins-lts.plist

2) 블록에 EnvironmentVariables 키 추가

docker, brew, 기타 CLI 도구들이 위치한 경로를 모두 포함시켜야 합니다!

<key>EnvironmentVariables</key>
<dict>
  <key>PATH</key>
  <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin</string>
</dict>

3) Jenkins 서비스 재시작

brew services restart jenkins-lts

결과