Jenkins Pipeline에서 Node.js 버전 고정하는 방법 — tools 블록과 NodeJS 플러그인 설정

빌드 서버 환경에 따라 발생하는 Jenkins Node.js 버전 갈등의 원인

단일 젠킨스(Jenkins) 서버에서 다양한 성격의 백엔드와 프론트엔드 프로젝트 빌드를 혼재해 실행하다 보면, 운영체제 전역에 깔려 있는 기본 Node.js 버전을 놓고 갈등이 생기게 마련입니다. 특정 서비스는 구형 라이브러리 때문에 Node 16 버전을 고집해야 하고, 신규 Next.js 서비스는 Node 20 이상 버전을 요구할 때, 서버 관리자가 글로벌 버전 노드를 임의로 교체해 버리면 멀쩡히 작동하던 다른 빌드 스케줄이 한순간에 엉망이 되며 빨간불을 뿜기 일쑤죠. 이처럼 공유 인프라 환경의 소스 노드가 통제 불능으로 흔들리게 두는 것은 CI/CD 파이프라인의 신뢰성을 위협하는 최악의 조건입니다. 팀원이 로컬에서 코드를 짤 때 썼던 버전과 통합 빌드 엔진이 돌아가는 런타임 버전을 일대일로 강제 일치시켜 두어야 기계적인 린트 검사나 빌드 최적화 에러의 고통 없이 깨끗한 배포 결과물을 보장받을 수 있습니다.

의존성 버전을 명시하여 빌드를 지키는 Jenkins Pipeline tools 블록

이러한 버전 격차 현상을 가장 깔끔하게 종식시켜 주는 핵심 기술이 바로 Jenkinsfile의 tools 구문 스펙입니다. 파이프라인 최상단에 빌드용 툴셋 규칙을 명시적으로 달아두면, Jenkins는 서버 환경에 전역 설치된 지저분한 패스 정보를 깨끗이 무시하고, 지정한 타겟 버전의 Node.js 바이너리를 컨테이너 가상망 내부로 동적 링킹하여 빌드 샌드박스를 격리 설계해 줍니다. 이렇게 작성된 배포 명세서는 빌드에 참여하는 팀원 누구나 한눈에 프로젝트 환경 요구 규격을 파악할 수 있는 스펙 문서의 역할까지 겸하므로, 개발 프로세스의 완성도를 높여주는 모던 DevOps의 필수적인 표준 구축 기법입니다.

CI 서버 관리를 위한 Jenkins NodeJS 플러그인 설치 과정

이 도구 격리 기술을 구사하려면 먼저 Jenkins 시스템 내에 'NodeJS' 플러그인이 가입되어 있어야 합니다. 관리 콘솔에 들어간 뒤 플러그인 매니저 메뉴의 Available plugins 탭에서 NodeJS를 검색해 간편하게 클릭 설치를 단행하면 되죠. 만약 내부망 보안 방화벽이 삼엄하게 차단된 온프레미스 인프라 환경이라 깃허브 외부 다운로드가 막혀 있다면, 수동으로 플러그인 파일(.hpi)을 내려받아 업로드하는 어드밴스드 설정을 활용해 해결할 수도 있습니다. 설치를 성공적으로 마치고 Jenkins 인스턴스를 한 번 가볍게 재기동해 주고 나면, 시스템 글로벌 도구 관리 페이지 하단에 새로운 NodeJS 전용 연동 스키마 섹션이 개설되며 사전 셋업 단계가 안전하게 마감됩니다.

글로벌 설정 메뉴에서 고유한 Jenkins NodeJS 도구 버전 등록하기

플러그인 등록에 이어서 해야 할 필수 조치는 바로 실제 프로젝트가 사용할 바이너리 세트를 Jenkins Tools 메뉴에서 미리 조율해 두는 것입니다. 설정 탭의 NodeJS 항목으로 들어가 'Add NodeJS' 버튼을 탭하면 입력창이 열리는데, 여기서의 핵심 요령은 식별 Name을 누구나 직관적으로 알 수 있게 깔끔하게 지정하는 것입니다. 예컨대 'NodeJS 18' 혹은 'NodeJS 20'과 같이 적어주고, 하단 드롭다운 목록에서 해당하는 노드 배포판 버전을 고른 뒤 'Install automatically' 스위치를 체크해 둡니다. 이 스위치가 활성화되어 있어야만, 향후 실제 빌드가 수행되는 시점에 젠킨스가 웹에서 바이너리를 찰나의 순간 자동으로 긁어와 임시 적재 디렉토리에 링크하여 무결한 버전 격리망을 가동시킵니다.

설정된 이름을 매핑하는 Jenkinsfile tools 블록 적용법

준비를 완료했다면 이제 프로젝트 루트의 Jenkinsfile을 켜고 pipeline 블록 내부, stages가 시작되기 전 지점에 tools 명령어를 할당해 줍니다. 구문으로 nodejs 'NodeJS 18'과 같이 적어주면 되는데, 이때 따옴표 안에 기술할 문자열은 앞서 글로벌 툴 메뉴에 입력해 두었던 식별 이름과 공백, 대소문자 단 한 글자도 틀리지 않고 완전히 일치해야만 젠킨스가 정상으로 맵핑을 이행합니다. 만약 텍스트 오타나 대소문자 미스매칭이 발생하면, 파이프라인이 깃 리포지토리에서 빌드 정의를 가져오자마자 'No tool named ...' 크래시 콘솔 에러를 내뿜고 1초 만에 뻗어버리는 불상사가 일어나니 꼭 주의하셔야 합니다.

pipeline {
  agent any
  tools {
    nodejs 'NodeJS 18' // Jenkins Global Tool Configuration에 등록한 Name과 정확히 일치해야 함
  }
  stages {
    stage('Setup Verification') {
      steps {
        // 고정된 노드 및 npm 패키지 버전이 잘 적용되었는지 로그에서 확인
        sh 'node --version'
        sh 'npm --version'
      }
    }
    stage('Install') {
      steps {
        sh 'npm ci'
      }
    }
    stage('Build') {
      steps {
        sh 'npm run build'
      }
    }
  }
}

버전이 바르게 물렸는지 로그를 통해 Jenkins Pipeline 빌드 확인하기

모든 코딩을 마쳐서 커밋 후 빌드를 켜면, 최초 가동 시 젠킨스가 명시된 바이너리를 동적으로 가져오는 파란색 인스톨 로그가 터미널에 흘러갑니다. 툴 체인이 무사히 적용되었는지 굳히기를 수행하기 위해, 파이프라인 시작부에 sh 'node --version' 검사 스텝을 끼워 넣어 출력되는 로그 텍스트를 관찰해 봅니다. 화면에 우리가 고정한 v18.x.x가 아름답게 찍혀 있는 것이 체크되면 성공입니다. 이제 서버 관리자나 타 팀 개발자가 글로벌 환경 변수 노드 패스를 무슨 버전으로 덮어쓰고 망가뜨려 놓더라도, 우리 프로젝트의 배포 라인은 한결같이 고정된 샌드박스 망 속에서 안정적으로 컴파일 테스트를 이행해 냅니다.