Publish Over SSH 플러그인 Remote Directory 설정 가이드

빌드 산출물이 배포 서버의 엉뚱한 경로에 배포된 경험이 있다면, Remote Directory 설정이 상대 경로로 되어 있지 않은지 확인해 보세요.

Jenkins Publish Over SSH 플러그인에서 Remote Directory 를 상대 경로로 지정하면, SSH 접속 계정의 홈 디렉토리를 기준으로 해석됩니다. 의도와 다른 경로에 파일이 배포되는 문제의 원인이 대부분 이것입니다.

문제 상황

상대 경로로 인한 배포 경로 오류

Remote Directory를 비워두면 기본적으로 SSH 접속 계정의 홈 디렉토리 가 기준 경로가 됩니다. 예를 들어, userA 계정으로 접속하면 /home/userA가 기준입니다.

여기서 Remote Directory를 절대 경로(/deploy/app)가 아닌 **상대 경로 **(deploy/app)로 입력하면, Jenkins는 홈 디렉토리를 기준으로 경로를 해석합니다.

Before / After 비교

** 원인:** Jenkins Publish Over SSH 플러그인은 상대 경로를 SSH 접속 계정의 홈 디렉토리 기준으로 해석합니다. 따라서 /로 시작하지 않는 경로는 항상 홈 디렉토리 하위에 매핑됩니다.

해결 방법

방법 1: 절대 경로 사용 (권장)

Remote Directory에 항상 /로 시작하는 절대 경로를 지정합니다.

steps {
    sshPublisher(
        publishers: [
            sshPublisherDesc(
                configName: env.SERVER_NAME,
                transfers: [
                    sshTransfer(
                        sourceFiles: 'target/*.jar',
                        remoteDirectory: '/deploy/app/lib',  // 절대 경로
                        removePrefix: 'target',
                        execCommand: """
                            echo 'Deployed to /deploy/app/lib';
                            ls -l /deploy/app/lib
                        """
                    )
                ],
                verbose: true
            )
        ]
    )
}

방법 2: 서버 설정에서 기준 경로를 루트(/)로 지정

Manage Jenkins > System > SSH Servers 에서 서버를 추가할 때, Remote Directory를 /(루트)로 설정해두면, 이후 파이프라인 스크립트에서 상대 경로를 사용해도 루트 기준으로 해석됩니다.

베스트 프랙티스

1. Remote Directory는 항상 절대 경로를 사용합니다. 상대 경로로 인한 혼란을 원천 차단할 수 있습니다.
2. ** 환경 변수를 활용합니다.** Jenkins Credentials에 배포 경로를 저장하고 ${env.REMOTE_DIR} 형태로 참조하면, 경로 변경 시 코드 수정 없이 Jenkins 설정에서만 변경할 수 있습니다.
3. SSH Server의 기준 경로를 루트(/)로 설정합니다. 서버 추가 시 기준 경로를 /로 설정하면, 스크립트에서 지정한 경로가 그대로 절대 경로로 사용됩니다.

배포 경로 설정은 작은 부분처럼 보이지만, 잘못 설정하면 운영 서버의 엉뚱한 위치에 파일이 배포되어 장애로 이어질 수 있습니다. 처음 설정할 때 절대 경로 규칙을 확립해두는 것이 중요합니다.

정리